3.软件开发文档管理规范
合集下载
相关主题
- 1、下载文档前请自行甄别文档内容的完整性，平台不提供额外的编辑、内容补充、找答案等附加服务。
- 2、"仅部分预览"的文档,不可在线预览部分如存在完整性等问题,可反馈申请退款(可完整预览的文档不适用该条件!)。
- 3、如文档侵犯您的权益，请联系客服反馈,我们会尽快为您处理(人工客服工作时间：9:00-18:30)。
客户需求细节的了解 技术重点和难点的分析 系统结构的设计与划分
• 完成概要设计的过程
第一步：功能描述（Function Description） 第二步：功能定义（Function Specification）
第三步：重点难点问题解决思路
第四步：概要设计草案
软件项目管理培训之三——文档规范 2018年6月 22日 20
软件项目管理培训之三——文档规范
2018年6月 22日
28
Thanks for your time! Questions & Answers
软件项目管理培训之三——文档规范
2018年6月 22日
29
技巧1：提供统一的项目背景资料 技巧2：培养一致的文档编写习惯 技巧3：明确要求表格和图形的使用方式
软件项目管理培训之三——文档规范 2018年6月 22日
18
文档管理方法：如何写好需求分析
• 做好需求分析的前提条件
• • •
• • • •
客户应用环境的了解
市场主流与技术主流的了解 客户现有需求的总结和潜在需求的挖掘
进度变更记录
职责定义
软件项目管理培训之三——文档规范
2018年6月 22日
10
文档的等级（1）
• 确定文档质量等级
•
根据项目资源、项目大小和风险确定每个文档的格式及详细 程度
• •
文档格式和文档内容同样重要
必须保证文档的质量，文档管理才有意义
软件项目管理培训之三——文档规范
2018年6月 22日
11
• 有效性原则
文档必须能够起到辅助决策、指导参考的作用
• 延续性原则
•
文档的变化必须有合理依据，保持连续发展
软件项目管理培训之三——文档规范
2018年6月 22日
15
文档管理的内容
• 建立文档规范，培养良好习惯
• 制定编写计划，明确编写责任
• 检查文档质量，提高利用效率 • 控制文档范围，保护知识产权
研发/维护人员
研发/维护人员 研发/维护人员 管理/研发/维护人员 研发人员 研发/维护人员 管理人员 管理人员
设计阶段
设计阶段 设计阶段 实现、测试阶段 需求分析、设计阶段 测试阶段 贯穿整个开发过程 测试阶段
管 理 类
开发进度月报 项目开发总结
职责定义 进度变更记录
用户指南 操作手册
管理人员 管理人员
软件项目管理培训之三——文档规范
2018年6月 22日
13
内容提要
• 文档的分类和等级 • 文档管理的原则和方法 • 文档示例与讨论
软件项目管理培训之三——文档规范
2018年6月 22日
14
文档管理的基本原则
• 完整性原则
•
• •
项目文档集应覆盖软件开发的完整流程
• 简洁性原则
编写文档不应浪费过多的时间和经历
研发类项目概要设计与详细设计示例 应用类项目概要设计与详细设计示例 数据库与数据仓库类设计文档示例 测试计划与测试案例类文档示例
•
工作日志、周工作报告、里程碑报告文档示例
软件项目管理培训之三——文档规范
2018年6月 22日
27ห้องสมุดไป่ตู้
结束语
• 软件开发的过程就是文档管理的过程 • 代码容易遗忘，文档却长久闪光 • 建立文档规范是软件团队的成功之路
完成里程碑报告的过程
第三步：总结存在的问题、困难和障碍
第四步：列出下一个里程碑的主要工作计划
软件项目管理培训之三——文档规范 2018年6月 22日 22
文档管理方法：确定最小文档集
• 如何确定最小文档集
• • • • •
重要认识：最小文档集不是指最简单文档集 最重要、最必须的文档组成最小文档集
• 如何实现最小文档集
人员分工：多人协作完成一份文档 文档格式：提供统一易用的模板
内容组织：合并细节结构，保持总体完整
软件项目管理培训之三——文档规范
2018年6月 22日
23
反思：为什么中国人不善于写文档？
• 文化背景的原因
• • • • •
官修史与私修史：从孔子谈起 封建专制与思想禁锢：焚书坑儒和文字狱
• 现代教育的原因
2018年6月 22日
12
文档的等级（3）
• 文档按照质量可划分为四个等级：
• •
工作文档（3级文档）
• • •
适合于由同一单位内若干人联合开发的程序，或可被其他单位 使用的程序
正式文档（4级文档）
适合那些要正式发行供普遍使用的软件产品 关键性程序或具有重复管理应用性质（如工资计算）的程序需 要4级文档
用户 用户
可行性研究与计划阶段 随时
需求分析、设计、实现阶段 设计、实现阶段
产 品 类
信息广告
2018年6月22日
用户
软件项目管理培训之三——文档规范
测试阶段
6
文档的分类（2）
文件 数据需求说明书 项目开发计划 软件需求说明书 数据需求说明书 测试计划 概要设计说明书 详细设计说明书 数据库设计说明书 阶段 可行性研究 与计划阶段 需求分 析阶段 设计 阶段 实现 阶段 测试 阶段 运行与 维护阶段
注重版本控制，切忌顾此失彼
•
应用图文表格，保证内容清晰
文档的分类（1）
类型
可行性研究报告 项目开发计划 设 计 需求规格说明书 功能规格说明书
读者
管理/研发人员 管理/研发人员 研发人员 研发人员
时间
可行性研究与计划阶段 可行性研究、需求分析阶段 需求分析阶段 需求分析阶段
开
发 类
概要设计说明书
详细设计说明书 数据库设计说明书 模块开发卷宗 测试计划 测试分析报告
缺乏方法教育和人格教育 缺乏法律意识和严谨态度
官本位、钱本位的价值观
软件项目管理培训之三——文档规范
2018年6月 22日
24
内容提要
• 文档的分类和等级 • 文档管理的原则和方法 • 文档示例与讨论
软件项目管理培训之三——文档规范
2018年6月 22日
25
文档编写技巧
•
• • •
文档排版方法
• • •
4
编写文档的基本思路
• • • •
明确文档范围，避免空泛浮躁
• •
大而全的文档是没有用的 以读者能够理解作为编写文档的标准
定位读者角度，防止对牛弹琴 规范名词称谓，保持前后一致
•
• •
统一的名词和称谓，会降低文档的歧义性
不同阶段的文档记录了项目开发的完整过程 简洁的图形和表格胜过前言万语
软件项目管理培训之三——文档规范 2018年6月 22日 5
模块开发卷宗
用户手册 操作手册 测试分析报告 开发进度月报
项目开发总结
2018年6月22日
软件项目管理培训之三——文档规范
7
文档的分类（3）
开发文档
可 行 性 研 究 报 告
项 目 开 发 计 划
需 求 规 格 说 明 书
功 能 规 格 说 明 书
概 要 设 计 说 明 书
详 细 设 计 说 明 书
问题：你会用MS Word吗？ 问题：你会用MS Visio和MS Excel吗？ 问题：如何设计良好的文件夹结构？ 问题：如何对自己的项目进行文档命名？
图表制作方法 文档分类结构 文档命名方式
•
软件项目管理培训之三——文档规范
2018年6月 22日
26
文档示例与讨论
•
• • • •
需求分析文档示例
软件项目管理培训讲 座
系列之三——文档管理规范
内容提要
• 文档的分类和等级 • 文档管理的原则和方法 • 文档示例与讨论
2018年6月 22日
软件项目管理培训之三——文档规范
2
为什么需要文档管理？
•
项目管理的依据
•
•
• • • •
了解进度、分析问题，提供项目可预见性 口说无凭，立字为据 没有文档，测试人员无法展开工作 帮助外界人员了解项目内幕 帮助技术支持人员熟悉系统、分析错误、解决问题 软件最大的价值在于可复用性
文档的等级（2）
• 文档按照质量可划分为四个等级：
• •
最低限度文档（1级文档）
• • • •
适合开发工作量低于一个人月的开发者自用程序 包含程序清单、开发记录、测试数据和程序简介
内部文档（2级文档）
适合于没有与其他用户共享资源的专用程序 1级文档内容，加上足够的注释和说明
软件项目管理培训之三——文档规范
第四步：详细设计草案
软件项目管理培训之三——文档规范 2018年6月 22日 21
文档管理方法：如何写好里程碑报告
•
里程碑报告的内容
•
• • • • • • • •
预期目标的解释和说明 已完成工作的说明 进度情况、测试结果的分析和说明 下一步工作的重点和难点 第一步：分析前一个里程碑报告的内容 第二步：说明当前里程碑的主要进展
• 完成需求分析的过程
第一步：项目建议书（Proposal） 第二步：市场与技术调研报告（M&T Report)
第三步：需求变更风险分析
第四步：需求分析初稿
软件项目管理培训之三——文档规范 2018年6月 22日 19
文档管理方法：如何写好概要设计
• 做好概要设计的前提条件
• • •
• • • •
技巧2：同类型多个文档的命名方法
技巧3：文档存储和管理的方法
软件项目管理培训之三——文档规范 2018年6月 22日 17
文档管理方法：如何保证内容完整？
• 内容残缺的体现
• • •
• • •
缺少项目背景和内容目录（举例）
缺少表格和示意图（举例） 缺少对思想的阐述和问题的分析（举例）
• 保证内容完整的方法
文档管理方法：如何写好详细设计
• 详细设计的底线是什么？
• • •
• • • •
主要处理流程的详细说明
对外接口的详细说明 主要逻辑结构和数据结构的详细说明
• 完成详细设计的过程
第一步：流程定义（Control Flow） 第二步：数据结构定义（Data Flow)
第三步：接口定义（API Specification）
软件项目管理培训之三——文档规范 2018年6月 22日 3
工作交流的凭证
软件测试的基础
•
• •
培训用户的参考
技术支持的帮手
•
•
记录历史的必须
为什么需要文档管理？ 按规范要求生成一整套文档的 过程，就是按照软件开发规范 完成一个软件开发的过程。
软件项目管理培训之三——文档规范
2018年6月 22日
数 据 库 设 计 说 明 书
模 块 开 发 卷 宗
测 试 计 划
测 试 分 析 报 告
软件项目管理培训之三——文档规范
2018年6月 22日
8
文档的分类（4）
产品文档
用户指南
操作手册
产品手册
用户指南
软件项目管理培训之三——文档规范
2018年6月 22日
9
文档的分类（5）
管理文档
开发进度月报
项目开发总结
• 实施版本控制，有效记录历史
软件项目管理培训之三——文档规范 2018年6月 22日 16
文档管理方法：如何命名？
• 命名规范的重要性
• • •
• • • •
统一的对外形象（举例）
有效的文档分类（举例） 快速的文档查找（举例）
• 命名规则的制定
并无统一规则，依据项目环境自定义 技巧1：确定统一的空白封面和项目名称
• 完成概要设计的过程
第一步：功能描述（Function Description） 第二步：功能定义（Function Specification）
第三步：重点难点问题解决思路
第四步：概要设计草案
软件项目管理培训之三——文档规范 2018年6月 22日 20
软件项目管理培训之三——文档规范
2018年6月 22日
28
Thanks for your time! Questions & Answers
软件项目管理培训之三——文档规范
2018年6月 22日
29
技巧1：提供统一的项目背景资料 技巧2：培养一致的文档编写习惯 技巧3：明确要求表格和图形的使用方式
软件项目管理培训之三——文档规范 2018年6月 22日
18
文档管理方法：如何写好需求分析
• 做好需求分析的前提条件
• • •
• • • •
客户应用环境的了解
市场主流与技术主流的了解 客户现有需求的总结和潜在需求的挖掘
进度变更记录
职责定义
软件项目管理培训之三——文档规范
2018年6月 22日
10
文档的等级（1）
• 确定文档质量等级
•
根据项目资源、项目大小和风险确定每个文档的格式及详细 程度
• •
文档格式和文档内容同样重要
必须保证文档的质量，文档管理才有意义
软件项目管理培训之三——文档规范
2018年6月 22日
11
• 有效性原则
文档必须能够起到辅助决策、指导参考的作用
• 延续性原则
•
文档的变化必须有合理依据，保持连续发展
软件项目管理培训之三——文档规范
2018年6月 22日
15
文档管理的内容
• 建立文档规范，培养良好习惯
• 制定编写计划，明确编写责任
• 检查文档质量，提高利用效率 • 控制文档范围，保护知识产权
研发/维护人员
研发/维护人员 研发/维护人员 管理/研发/维护人员 研发人员 研发/维护人员 管理人员 管理人员
设计阶段
设计阶段 设计阶段 实现、测试阶段 需求分析、设计阶段 测试阶段 贯穿整个开发过程 测试阶段
管 理 类
开发进度月报 项目开发总结
职责定义 进度变更记录
用户指南 操作手册
管理人员 管理人员
软件项目管理培训之三——文档规范
2018年6月 22日
13
内容提要
• 文档的分类和等级 • 文档管理的原则和方法 • 文档示例与讨论
软件项目管理培训之三——文档规范
2018年6月 22日
14
文档管理的基本原则
• 完整性原则
•
• •
项目文档集应覆盖软件开发的完整流程
• 简洁性原则
编写文档不应浪费过多的时间和经历
研发类项目概要设计与详细设计示例 应用类项目概要设计与详细设计示例 数据库与数据仓库类设计文档示例 测试计划与测试案例类文档示例
•
工作日志、周工作报告、里程碑报告文档示例
软件项目管理培训之三——文档规范
2018年6月 22日
27ห้องสมุดไป่ตู้
结束语
• 软件开发的过程就是文档管理的过程 • 代码容易遗忘，文档却长久闪光 • 建立文档规范是软件团队的成功之路
完成里程碑报告的过程
第三步：总结存在的问题、困难和障碍
第四步：列出下一个里程碑的主要工作计划
软件项目管理培训之三——文档规范 2018年6月 22日 22
文档管理方法：确定最小文档集
• 如何确定最小文档集
• • • • •
重要认识：最小文档集不是指最简单文档集 最重要、最必须的文档组成最小文档集
• 如何实现最小文档集
人员分工：多人协作完成一份文档 文档格式：提供统一易用的模板
内容组织：合并细节结构，保持总体完整
软件项目管理培训之三——文档规范
2018年6月 22日
23
反思：为什么中国人不善于写文档？
• 文化背景的原因
• • • • •
官修史与私修史：从孔子谈起 封建专制与思想禁锢：焚书坑儒和文字狱
• 现代教育的原因
2018年6月 22日
12
文档的等级（3）
• 文档按照质量可划分为四个等级：
• •
工作文档（3级文档）
• • •
适合于由同一单位内若干人联合开发的程序，或可被其他单位 使用的程序
正式文档（4级文档）
适合那些要正式发行供普遍使用的软件产品 关键性程序或具有重复管理应用性质（如工资计算）的程序需 要4级文档
用户 用户
可行性研究与计划阶段 随时
需求分析、设计、实现阶段 设计、实现阶段
产 品 类
信息广告
2018年6月22日
用户
软件项目管理培训之三——文档规范
测试阶段
6
文档的分类（2）
文件 数据需求说明书 项目开发计划 软件需求说明书 数据需求说明书 测试计划 概要设计说明书 详细设计说明书 数据库设计说明书 阶段 可行性研究 与计划阶段 需求分 析阶段 设计 阶段 实现 阶段 测试 阶段 运行与 维护阶段
注重版本控制，切忌顾此失彼
•
应用图文表格，保证内容清晰
文档的分类（1）
类型
可行性研究报告 项目开发计划 设 计 需求规格说明书 功能规格说明书
读者
管理/研发人员 管理/研发人员 研发人员 研发人员
时间
可行性研究与计划阶段 可行性研究、需求分析阶段 需求分析阶段 需求分析阶段
开
发 类
概要设计说明书
详细设计说明书 数据库设计说明书 模块开发卷宗 测试计划 测试分析报告
缺乏方法教育和人格教育 缺乏法律意识和严谨态度
官本位、钱本位的价值观
软件项目管理培训之三——文档规范
2018年6月 22日
24
内容提要
• 文档的分类和等级 • 文档管理的原则和方法 • 文档示例与讨论
软件项目管理培训之三——文档规范
2018年6月 22日
25
文档编写技巧
•
• • •
文档排版方法
• • •
4
编写文档的基本思路
• • • •
明确文档范围，避免空泛浮躁
• •
大而全的文档是没有用的 以读者能够理解作为编写文档的标准
定位读者角度，防止对牛弹琴 规范名词称谓，保持前后一致
•
• •
统一的名词和称谓，会降低文档的歧义性
不同阶段的文档记录了项目开发的完整过程 简洁的图形和表格胜过前言万语
软件项目管理培训之三——文档规范 2018年6月 22日 5
模块开发卷宗
用户手册 操作手册 测试分析报告 开发进度月报
项目开发总结
2018年6月22日
软件项目管理培训之三——文档规范
7
文档的分类（3）
开发文档
可 行 性 研 究 报 告
项 目 开 发 计 划
需 求 规 格 说 明 书
功 能 规 格 说 明 书
概 要 设 计 说 明 书
详 细 设 计 说 明 书
问题：你会用MS Word吗？ 问题：你会用MS Visio和MS Excel吗？ 问题：如何设计良好的文件夹结构？ 问题：如何对自己的项目进行文档命名？
图表制作方法 文档分类结构 文档命名方式
•
软件项目管理培训之三——文档规范
2018年6月 22日
26
文档示例与讨论
•
• • • •
需求分析文档示例
软件项目管理培训讲 座
系列之三——文档管理规范
内容提要
• 文档的分类和等级 • 文档管理的原则和方法 • 文档示例与讨论
2018年6月 22日
软件项目管理培训之三——文档规范
2
为什么需要文档管理？
•
项目管理的依据
•
•
• • • •
了解进度、分析问题，提供项目可预见性 口说无凭，立字为据 没有文档，测试人员无法展开工作 帮助外界人员了解项目内幕 帮助技术支持人员熟悉系统、分析错误、解决问题 软件最大的价值在于可复用性
文档的等级（2）
• 文档按照质量可划分为四个等级：
• •
最低限度文档（1级文档）
• • • •
适合开发工作量低于一个人月的开发者自用程序 包含程序清单、开发记录、测试数据和程序简介
内部文档（2级文档）
适合于没有与其他用户共享资源的专用程序 1级文档内容，加上足够的注释和说明
软件项目管理培训之三——文档规范
第四步：详细设计草案
软件项目管理培训之三——文档规范 2018年6月 22日 21
文档管理方法：如何写好里程碑报告
•
里程碑报告的内容
•
• • • • • • • •
预期目标的解释和说明 已完成工作的说明 进度情况、测试结果的分析和说明 下一步工作的重点和难点 第一步：分析前一个里程碑报告的内容 第二步：说明当前里程碑的主要进展
• 完成需求分析的过程
第一步：项目建议书（Proposal） 第二步：市场与技术调研报告（M&T Report)
第三步：需求变更风险分析
第四步：需求分析初稿
软件项目管理培训之三——文档规范 2018年6月 22日 19
文档管理方法：如何写好概要设计
• 做好概要设计的前提条件
• • •
• • • •
技巧2：同类型多个文档的命名方法
技巧3：文档存储和管理的方法
软件项目管理培训之三——文档规范 2018年6月 22日 17
文档管理方法：如何保证内容完整？
• 内容残缺的体现
• • •
• • •
缺少项目背景和内容目录（举例）
缺少表格和示意图（举例） 缺少对思想的阐述和问题的分析（举例）
• 保证内容完整的方法
文档管理方法：如何写好详细设计
• 详细设计的底线是什么？
• • •
• • • •
主要处理流程的详细说明
对外接口的详细说明 主要逻辑结构和数据结构的详细说明
• 完成详细设计的过程
第一步：流程定义（Control Flow） 第二步：数据结构定义（Data Flow)
第三步：接口定义（API Specification）
软件项目管理培训之三——文档规范 2018年6月 22日 3
工作交流的凭证
软件测试的基础
•
• •
培训用户的参考
技术支持的帮手
•
•
记录历史的必须
为什么需要文档管理？ 按规范要求生成一整套文档的 过程，就是按照软件开发规范 完成一个软件开发的过程。
软件项目管理培训之三——文档规范
2018年6月 22日
数 据 库 设 计 说 明 书
模 块 开 发 卷 宗
测 试 计 划
测 试 分 析 报 告
软件项目管理培训之三——文档规范
2018年6月 22日
8
文档的分类（4）
产品文档
用户指南
操作手册
产品手册
用户指南
软件项目管理培训之三——文档规范
2018年6月 22日
9
文档的分类（5）
管理文档
开发进度月报
项目开发总结
• 实施版本控制，有效记录历史
软件项目管理培训之三——文档规范 2018年6月 22日 16
文档管理方法：如何命名？
• 命名规范的重要性
• • •
• • • •
统一的对外形象（举例）
有效的文档分类（举例） 快速的文档查找（举例）
• 命名规则的制定
并无统一规则，依据项目环境自定义 技巧1：确定统一的空白封面和项目名称