第4章 软件文档写作要求PPT课件
合集下载
相关主题
- 1、下载文档前请自行甄别文档内容的完整性，平台不提供额外的编辑、内容补充、找答案等附加服务。
- 2、"仅部分预览"的文档,不可在线预览部分如存在完整性等问题,可反馈申请退款(可完整预览的文档不适用该条件!)。
- 3、如文档侵犯您的权益，请联系客服反馈,我们会尽快为您处理(人工客服工作时间：9:00-18:30)。
• 产生哪些文档，详细程度如何。 • 各个文档编制负责人和进度要求。 • 审查、批准的负责人和进度要求。 • 文档的维护、修改和管理的负责人，以及批准手续。
❖ 2.文档的详细程度取决于
▪ 项目规模 ▪ 项目复杂程度 ▪ 负责人对开发过程及运行环境的判断
2020/9/16
3
4.2 文档编写的灵活性
❖ 3.文档的扩展
操作手册 操作手册 安装实施过程
4
测试计划 测试计划 测试设计说明 测试规程 测试用例
测试分析报告 综合测试报告 验收测试报告
项目总结报告 项目开发总结报告 资源环境统计
4.2 文档编写的灵活性
❖ 4.章节的扩张与缩并
▪ 国标中提供的章、条都可以进行 扩展，同样有些细节条目也可Байду номын сангаас 删减和缩并。
❖ 5.程序设计的表现形式
▪ 为了方便文档的各自读者，每种文档都应自成体系。 ▪ 虽然有重复，但侧重点应该不同。
❖ 应具有一定的灵活性
▪ 软件规模和复杂度差别极大，文档编制中允许有一定的灵活性。
2020/9/16
2
4.2 文档编写的灵活性
❖ 1.编制的文档种类
▪ 虽然有14种文档，但根据实际情况可以合并。 ▪ 项目管理人员应该根据实际情况制定具体的文档编制任务：
• 语法、标点及其他行文技巧方面的正确性
• 对格式和别的标准的遵守程度 （对照研究生论文的格式要求）
2020/9/16
11
4.6 建立文档的编制规程
❖ 5.文档签署
▪ 文档不许代签，修改单的签署与被修改的文档签署应相同。
2020/9/16
12
4.6 建立文档的编制规程
❖ 6.文档归档与保管
▪ 集中、统一管理
• 工作文档（3级文档）
– 适合于由同一单位内若干人联合开发，或可被其他单位使用。
• 正式文档（4级文档）
– 适合那些正式发行供普遍使用的软件产品，遵守GB/T 8567-1988的有关 规定。
2020/9/16
8
4.5 制定文档的编制计划
❖ 文档计划作为整个项目的一部分或一个独立工作， 应该分发给开发组成员，编制计划应该尽早开始， 一般包括以下内容：
▪ 列出应编制文档的目录 ▪ 提示编制文档应参考的标准 ▪ 指定文档管理员 ▪ 提供所需条件，落实编写人员、经费和工具 ▪ 明确保证质量的方法，采取评审或鉴定等 ▪ 绘制进度表，确定开始日期、完成日期、评审日期
表4.2 文档计划检查表 P60
2020/9/16
9
4.6 建立文档的编制规程
❖ 1.文档计划制定 ❖ 2.文档编写
❖ 7.文档维护
2020/9/16
13
4.7 软件文档的质量要求
❖ 造成文档质量不高的原因
▪ 缺乏实践经验，缺乏评价文档质量的标准 ▪ 不重视文档编写工作，或是对文档编写工作安排不当
• 不是同步进行，而是集中人力集中时间编写 • 与程序工作相比，没有兴趣，应付一下
❖ 高质量文档具备的特点
▪ 针对性 ▪ 精确性 ▪ 清晰性 ▪ 完整性 ▪ 灵活性 ▪ 可追溯性
软件文档与标准
第4章 软件文档及写作要求
2020/9/16
1
4.1 软件文档的编写原则
❖ 应适应文档的读者
▪ 个人、小组 ▪ 开发成员、社会公众 ▪ 软件技术人员、领域业务人员 ▪ 底层工作人员、上层管理人员。
❖ 应有必要的重复性
▪ 国标规定的14中文档中就有大量的重复（如引言部分和说明部 分）。
当系统规模非常大，如超过100万行，一种文档可以分成几卷编写，也 可按子系统分别编写。文档的内容可以进行如下扩展：
2020/9/16
项目开发计划 质量保证计划 配置管理计划 用户培训计划 安装实施计划
系统设计说明书 系统概要设计说明
书 子系统设计说明书
程序设计说明书 程序设计说明书 接口设计说明书 版本说明书
❖ 3.文档编号
▪ 例如：WD_GLYX_SRS_040420 （起名的技巧：方便排序与查询）
❖ 4.文档评价
▪ 评审内容：内容准确、版本最新
▪ 需求评审：可能多次
▪ 设计评审
▪ 其他评审
• 编排方式
• 技术准确度 • 覆盖范围的完整性
表4.5 各评审点评审内容 P63
• 对读者的适合程度
• 图表设计思想及最终图表
5
4.3 制定文档的编写策略
❖ 文档策略是由资深管理者提出的，支持有效文档 策略的基本条件如下：
▪ 文档需要覆盖整个软件生存期 ▪ 文档应是可管理的 ▪ 文档应适合于它的读者 ▪ 文档效应应贯穿到软件的整个开发过程中 ▪ 文档标准应被标识和使用 ▪ 应规定支持工具 （visio，mindview）
表4.1 文档策略检查表 P57
2020/9/16
6
Matchware mindview (思维可视化-文档工具)
2020/9/16
7
4.4 建立文档的企业标准
❖ 企业应尽可能采用现行国家和国际标准，若现行标准不适用，可以指 定自己的标准。
▪ 选择软件生存期模型 • 采用哪种模型不重要，重要的是模型的阶段和对应的文档定义清晰。
2020/9/16
14
4.8 软件文档的编写技巧
❖ 从技术的角度进行文档的编写和评价
▪ 注意力集中于技术事实，保证步骤图片文字的准确性。
❖ 明确文档编写人员的责任
▪ 规定文档类型和内容 • 开发文档、用户文档、管理文档
▪ 确定文档的质量等级 • 最低限度文档（1级文档）
– 适合工作量低于一个人月的开发者自用，包括程序清单、开发记录、测 试数据和程序简介。
• 内部文档（2级文档）
– 没有与其他用户共享资源的专用文档，除了1级文档提供的信息外还包括 足够的注释以帮助用户安装和使用。
▪ 流程图 ▪ 判定表 ▪ 程序设计语言（PDL） ▪ 问题分析图（PAD）
❖ 6.文档的表现形式
▪ 没有具体规定 ▪ 自然语言或形式化语言
❖ 7.文档的其他种类
▪ 针对特殊需求建立特殊文档
1
2 3 45
觉得疲倦？ Y Y N N 条件
感兴趣吗？ N Y Y N
重读
动作
继续 跳下一章
√ √
休息
√√
2020/9/16
▪ 与软件开发同步（表4.4） ▪ 按照计划规定的数量、质量编写 ▪ 按标准指定的内容和格式编写 ▪ 文档用纸 ▪ 装订成册，并加装封面和目录 ▪ 归档文档还应有扉页，用于各责任者的签署
“→”表示文档开始 的时间，但不持续整 个阶段。 “O”表示要进行评 审活动。
2020/9/16
10
4.6 建立文档的编制规程
❖ 2.文档的详细程度取决于
▪ 项目规模 ▪ 项目复杂程度 ▪ 负责人对开发过程及运行环境的判断
2020/9/16
3
4.2 文档编写的灵活性
❖ 3.文档的扩展
操作手册 操作手册 安装实施过程
4
测试计划 测试计划 测试设计说明 测试规程 测试用例
测试分析报告 综合测试报告 验收测试报告
项目总结报告 项目开发总结报告 资源环境统计
4.2 文档编写的灵活性
❖ 4.章节的扩张与缩并
▪ 国标中提供的章、条都可以进行 扩展，同样有些细节条目也可Байду номын сангаас 删减和缩并。
❖ 5.程序设计的表现形式
▪ 为了方便文档的各自读者，每种文档都应自成体系。 ▪ 虽然有重复，但侧重点应该不同。
❖ 应具有一定的灵活性
▪ 软件规模和复杂度差别极大，文档编制中允许有一定的灵活性。
2020/9/16
2
4.2 文档编写的灵活性
❖ 1.编制的文档种类
▪ 虽然有14种文档，但根据实际情况可以合并。 ▪ 项目管理人员应该根据实际情况制定具体的文档编制任务：
• 语法、标点及其他行文技巧方面的正确性
• 对格式和别的标准的遵守程度 （对照研究生论文的格式要求）
2020/9/16
11
4.6 建立文档的编制规程
❖ 5.文档签署
▪ 文档不许代签，修改单的签署与被修改的文档签署应相同。
2020/9/16
12
4.6 建立文档的编制规程
❖ 6.文档归档与保管
▪ 集中、统一管理
• 工作文档（3级文档）
– 适合于由同一单位内若干人联合开发，或可被其他单位使用。
• 正式文档（4级文档）
– 适合那些正式发行供普遍使用的软件产品，遵守GB/T 8567-1988的有关 规定。
2020/9/16
8
4.5 制定文档的编制计划
❖ 文档计划作为整个项目的一部分或一个独立工作， 应该分发给开发组成员，编制计划应该尽早开始， 一般包括以下内容：
▪ 列出应编制文档的目录 ▪ 提示编制文档应参考的标准 ▪ 指定文档管理员 ▪ 提供所需条件，落实编写人员、经费和工具 ▪ 明确保证质量的方法，采取评审或鉴定等 ▪ 绘制进度表，确定开始日期、完成日期、评审日期
表4.2 文档计划检查表 P60
2020/9/16
9
4.6 建立文档的编制规程
❖ 1.文档计划制定 ❖ 2.文档编写
❖ 7.文档维护
2020/9/16
13
4.7 软件文档的质量要求
❖ 造成文档质量不高的原因
▪ 缺乏实践经验，缺乏评价文档质量的标准 ▪ 不重视文档编写工作，或是对文档编写工作安排不当
• 不是同步进行，而是集中人力集中时间编写 • 与程序工作相比，没有兴趣，应付一下
❖ 高质量文档具备的特点
▪ 针对性 ▪ 精确性 ▪ 清晰性 ▪ 完整性 ▪ 灵活性 ▪ 可追溯性
软件文档与标准
第4章 软件文档及写作要求
2020/9/16
1
4.1 软件文档的编写原则
❖ 应适应文档的读者
▪ 个人、小组 ▪ 开发成员、社会公众 ▪ 软件技术人员、领域业务人员 ▪ 底层工作人员、上层管理人员。
❖ 应有必要的重复性
▪ 国标规定的14中文档中就有大量的重复（如引言部分和说明部 分）。
当系统规模非常大，如超过100万行，一种文档可以分成几卷编写，也 可按子系统分别编写。文档的内容可以进行如下扩展：
2020/9/16
项目开发计划 质量保证计划 配置管理计划 用户培训计划 安装实施计划
系统设计说明书 系统概要设计说明
书 子系统设计说明书
程序设计说明书 程序设计说明书 接口设计说明书 版本说明书
❖ 3.文档编号
▪ 例如：WD_GLYX_SRS_040420 （起名的技巧：方便排序与查询）
❖ 4.文档评价
▪ 评审内容：内容准确、版本最新
▪ 需求评审：可能多次
▪ 设计评审
▪ 其他评审
• 编排方式
• 技术准确度 • 覆盖范围的完整性
表4.5 各评审点评审内容 P63
• 对读者的适合程度
• 图表设计思想及最终图表
5
4.3 制定文档的编写策略
❖ 文档策略是由资深管理者提出的，支持有效文档 策略的基本条件如下：
▪ 文档需要覆盖整个软件生存期 ▪ 文档应是可管理的 ▪ 文档应适合于它的读者 ▪ 文档效应应贯穿到软件的整个开发过程中 ▪ 文档标准应被标识和使用 ▪ 应规定支持工具 （visio，mindview）
表4.1 文档策略检查表 P57
2020/9/16
6
Matchware mindview (思维可视化-文档工具)
2020/9/16
7
4.4 建立文档的企业标准
❖ 企业应尽可能采用现行国家和国际标准，若现行标准不适用，可以指 定自己的标准。
▪ 选择软件生存期模型 • 采用哪种模型不重要，重要的是模型的阶段和对应的文档定义清晰。
2020/9/16
14
4.8 软件文档的编写技巧
❖ 从技术的角度进行文档的编写和评价
▪ 注意力集中于技术事实，保证步骤图片文字的准确性。
❖ 明确文档编写人员的责任
▪ 规定文档类型和内容 • 开发文档、用户文档、管理文档
▪ 确定文档的质量等级 • 最低限度文档（1级文档）
– 适合工作量低于一个人月的开发者自用，包括程序清单、开发记录、测 试数据和程序简介。
• 内部文档（2级文档）
– 没有与其他用户共享资源的专用文档，除了1级文档提供的信息外还包括 足够的注释以帮助用户安装和使用。
▪ 流程图 ▪ 判定表 ▪ 程序设计语言（PDL） ▪ 问题分析图（PAD）
❖ 6.文档的表现形式
▪ 没有具体规定 ▪ 自然语言或形式化语言
❖ 7.文档的其他种类
▪ 针对特殊需求建立特殊文档
1
2 3 45
觉得疲倦？ Y Y N N 条件
感兴趣吗？ N Y Y N
重读
动作
继续 跳下一章
√ √
休息
√√
2020/9/16
▪ 与软件开发同步（表4.4） ▪ 按照计划规定的数量、质量编写 ▪ 按标准指定的内容和格式编写 ▪ 文档用纸 ▪ 装订成册，并加装封面和目录 ▪ 归档文档还应有扉页，用于各责任者的签署
“→”表示文档开始 的时间，但不持续整 个阶段。 “O”表示要进行评 审活动。
2020/9/16
10
4.6 建立文档的编制规程