《软件文档写作要求（数学与计算机学院）》由会员分享，可在线阅读，更多相关《软件文档写作要求（数学与计算机学院）（70页珍藏版）》请在金锄头文库上搜索。
1、数学与计算机学院 第四章 软件文档写作要求 数学与计算机学院 主要内容 v4 1 软件文档管理指南 v4 2 软件文档的编写原则 v4 3 制定文档的编写策略 v4 4建立文档的企业标准 v4 5 制定文档的编制计划 v4 6 建立文档的编制规程 v4 7 软件文档的质量要求 v4 8 软件文档的编写技巧 v4 9 确定软件文档类型的种 类 数学与计算机学院 4 1 软件文档管理指南 q 软件文档管理指南 GB16680 1996 制定的目的在于协助管理者在他们 的机构中产生有效的文档 其主要内容主 要涉及文档编制的策略 标准 规程 资 源和计划 数学与计算机学院 本指南规定管理者承担的职责
2、1 要求哪些类类型的文档 2 文档包含的内容 3 达到何种级别级别 的质质量水平 4 何时产时产 生何种文档 5 如何保存 维护文档以及如何进行通信 数学与计算机学院 4 2 软件文档的编写原则 文档编制的原则 文档编 写应适 应文档 的读者 文档编写 应有必要 的重复性 文档编写 应具有一 定灵活性 文 档 种 类 文文 档档 详详 细细 程程 度度 文文 档档 的的 扩扩 展展 节节 的的 扩扩 张张 与与 缩缩 并并 程序 设计 的表 现形 式 文 档 的 表 现 形 式 文 档 其 他 种 类 根据一个项目的规模 复杂性和成败风险 决定应编制 的文档种类及其详细 数学与计算机学院 4
3、2 软件文档的编写原则 文档编制的原则 文档编 写应适 应文档 的读者 文档编写 应有必要 的重复性 文档编写 应具有一 定灵活性 文 档 种 类 文文 档档 详详 细细 程程 度度 文文 档档 的的 扩扩 展展 节节 的的 扩扩 张张 与与 缩缩 并并 程序 设计 的表 现形 式 文 档 的 表 现 形 式 文 档 其 他 种 类 当被开发的项目规模非常大时 可以将一个文档拆分成 多个卷进行编制 数学与计算机学院 v项目开发计划可能包括 vl 质量保证计划 vl 配置管理计划 vl 用户培训计划 vl 安装实施计划 v系统设计说明书可分写成 vl 系统设计说明书 vl 子系统设计说明书 v程
4、序设计说明书可分写成 vl 程序设计说明书 vl 接口设计说明书 vl 版本说明 数学与计算机学院 v操作手册可分成以下内容 l操作手册 l安装实施过程 v测试计划可分成以下内容 l测试计划 l测试设计说明 l测试规程 l测试用例 v测试分析报告可分成以下内容 综合测试报告 验收测试报告 v项目开发总结报告也可分成项目开发总结报告和 资源环境统计 数学与计算机学院 4 2 软件文档的编写原则 文档编制的原则 文档编 写应适 应文档 的读者 文档编写 应有必要 的重复性 文档编写 应具有一 定灵活性 文 档 种 类 文文 档档 详详 细细 程程 度度 文文 档档 的的 扩扩 展展 节节 的的 扩
5、扩 张张 与与 缩缩 并并 程序 设计 的表 现形 式 文 档 的 表 现 形 式 文 档 其 他 种 类 所有的章节都可以进一步细分或缩并 以适应实际需要 要 数学与计算机学院 4 2 软件文档的编写原则 文档编制的原则 文档编 写应适 应文档 的读者 文档编写 应有必要 的重复性 文档编写 应具有一 定灵活性 文 档 种 类 文文 档档 详详 细细 程程 度度 文文 档档 的的 扩扩 展展 节节 的的 扩扩 张张 与与 缩缩 并并 程序 设计 的表 现形 式 文 档 的 表 现 形 式 文 档 其 他 种 类 程序的设计表现形式可以使用多种形式 如流程图 判定 表 等其他表现形式 数学与计
6、算机学院 v例 P 86 航空行李托运费的算 法 v按规定 重量不超过30公斤的行 李可免费托运 重量超过30公斤时 对超运部分 头等舱国内乘客收 4元 公斤 其它舱位国内乘客收6 元 公斤 外国乘客收费为国内乘 客的2倍 残疾乘客的收费为正常 乘客的1 2 数学与计算机学院 数学与计算机学院 数学与计算机学院 4 2 软件文档的编写原则 文档编制的原则 文档编 写应适 应文档 的读者 文档编写 应有必要 的重复性 文档编写 应具有一 定灵活性 文 档 种 类 文文 档档 详详 细细 程程 度度 文文 档档 的的 扩扩 展展 节节 的的 扩扩 张张 与与 缩缩 并并 程序 设计 的表 现形 式
7、 文 档 的 表 现 形 式 文 档 其 他 种 类 文档的表现形式可以使用自然语言 也可以使用形式化语言 数学与计算机学院 4 2 软件文档的编写原则 文档编制的原则 文档编 写应适 应文档 的读者 文档编写 应有必要 的重复性 文档编写 应具有一 定灵活性 文 档 种 类 文文 档档 详详 细细 程程 度度 文文 档档 的的 扩扩 展展 节节 的的 扩扩 张张 与与 缩缩 并并 程序 设计 的表 现形 式 文 档 的 表 现 形 式 文 档 其 他 种 类 数学与计算机学院 主要内容 v4 1 软件文档管理指南 v4 2 软件文档的编写原则 v4 3 制定文档的编写策略 v4 4建立文档的
8、企业标准 v4 5 制定文档的编制计划 v4 6 建立文档的编制规程 v4 7 软件文档的质量要求 v4 8 软件文档的编写技巧 v4 9 确定软件文档类型的种 类 数学与计算机学院 4 3 制定文档的编写策略 v文档策略是由上级 资深 管理者 提出并支持的 对下级开发单位或开 发人员提供指导 策略规定主要的方 向 而不是规定做什么或如何做 文档需要覆盖整个软件生存期 文档应是可管理的 文档应适合于它的读者 文档效应应贯穿到软件的整个开发过程中 文档标准应被标识和使用 应规定支持工具 文 档 策 略 数学与计算机学院 评估现有策略条款的有效性和完整性的 文档检查表 v 适当的文档的决策作出了吗
9、 v 涉及文档的策略声明发布了吗 v 负责开发文档和产品文档编写工作的人员或部门落 实了吗 v 用于文档编制的资源落实了吗 v 负责文档质量的人员或部门落实了吗 v 各管理层次和组织各分支之间的各种关系确定了吗 v 对于文档的编制 分发和维护等方面是否确定了职 责 所需活动和联系途径 v 所有的文档要求已列入整个项目开发计划表中了吗 v 适用的文档标准已确定了吗 v 是否已考虑采用支持工具和自动化的文档编制 数学与计算机学院 主要内容 v4 1 软件文档管理指南 v4 2 软件文档的编写原则 v4 3 制定文档的编写策略 v4 4建立文档的企业标准 v4 5 制定文档的编制计划 v4 6 建立
10、文档的编制规程 v4 7 软件文档的质量要求 v4 8 软件文档的编写技巧 v4 9 确定软件文档类型的种 类 数学与计算机学院 4 4建立文档的企业标准 v是不是每个人编写的文档质量都一样 如何确 定文档的质量 如何保证 v评价文档的质量主要从两个方面 文档的结构 其质量从各个组成部分的顺序和 总体安排的简单性来测定 文档的内容 从文档内容的正确性 完整性和 明确性来判断 数学与计算机学院 4 4建立文档的企业标准 在一个机构内部应采用一些标准和指南 软件生存期模型 文档类型和相互关系 文档质量 标准和指南作用 1 决定如何实现文档任务 2 提供一些准则以评价该机构内所产生的 软件文档的完整
11、性 可用性和适合性 尽可能地采用现行的国家和国际标准 若现 行的标准不适用 机构应制订自己的标准 数学与计算机学院 4 4建立文档的企业标准 1 选择软件生存期模型 2 规定文档类型和内容 3 确定文档的质量等级 数学与计算机学院 1 选择软件生存期模型 v软件生存周期模型无关紧要 但阶段和相应的文档 必须清晰定义 计划 并且适用具体的软件项目 v管理者应选择一个软件生存期模型并保证该模型 在他们机构内是适用的 v生存周期选择对管理者作用 v 1 软件周期中相应的阶段划分与各阶段定义将 有助于监控软件项目的进展 v 2 相应于特定阶段生成的文档可用作该阶段的 评审通过和完成的检验点 数学与计算
12、机学院 2规定文档类型和内容 v软件文档归入如下三种类别 开发文档 描述开发过程本身 产品文档 描述开发过程的产物 管理文档 记录项目管理的信息 以上内容已在P18软件文档的分类中讲过 数学与计算机学院 3 文档的质量等级 v文档的质量可以按文档的形式和要求划分为四 级 v 1 最低限度文档 1级文档 1级文档适合 开发工作量低于一个人月的软件 该文档应包含 程序清单 开发记录 测试数据和程序简介 v 2 内部文档 2级文档 2级文档可用于在 精心研究后被认为没有与其他用户共享资源的专 用程序 除1级文档提供的信息外 2级文档还包 括程序清单内足够的注释以帮助用户安装和使用 程序 数学与计算机
13、学院 v 3 工作文档 3级文档 3级文档适合于由同 一单位内若干人联合开发的程序 或可被其他单位 使用的程序 v 4 正式文档 4级文档 4级文档适合那些要 正式发行供普遍使用的软件产品 关键性程序或具 有重复管理应用性质 如工资计算 的程序需要4级 文档 4级文档遵守GB 8567的有关规定 数学与计算机学院 v质量从第1级到第四级 需要的投入和资源逐级 增加 质量保证机构必须处于适当的行政地位以 保证达到期望的质量等级 v为了保证文档的质量 主要从一下几个方面 v评审鉴定 v责任到人 v采用制作工具 数学与计算机学院 主要内容 v4 1 软件文档管理指南 v4 2 软件文档的编写原则 v
14、4 3 制定文档的编写策略 v4 4建立文档的企业标准 v4 5 制定文档的编制计划 v4 6 建立文档的编制规程 v4 7 软件文档的质量要求 v4 8 软件文档的编写技巧 v4 9 确定软件文档类型的种 类 数学与计算机学院 4 5制定文档的编制计划 文档计 划 1 制定文档计划的目的 2 文档计划的特点 3 文档计划的内容 4 文档计划制定与评估 数学与计算机学院 1 制定文档计划的目的 v指出未来的各项活动 v文档计划是文档重要性的具体依据 v管理部门文档工作责任的备忘录 数学与计算机学院 2 文档计划的特点 v文档计划可以是整个项目计划的一部分或是一个 独立的文档 v对于小的非正式的
15、项目文档计划可能只有一页纸 v对于较大的项目文档计划可能是一个综合性的正 式文档 这样的文档计划应遵循各项严格的标准及 正规的评审和批准过程 v编制计划的工作应及早开始 对计划的评审应贯 穿项目的全过程 v需要修改时必须加以修改 v导致对计划作适当修改的常规评审应作为该项目 工作的一部分 v所有与该计划有关的人员都应得到文档计划 数学与计算机学院 3 文档计划的内容 此外 1 文档计划规定每个文档要达到的质量等级 以及为 了达到期望的结果必须考虑哪些外部因素 2 文档计划还确定该计划和文档的分发 并且明确叙 述参与文档工作的所有人员的职责 数学与计算机学院 4 文档计划制定与评估 v可按照GB
16、16680 1996 软件文档管理指南 附录 B中文档计划检查表来制定一个文档计划或评估现 有文档计划的完整性 数学与计算机学院 数学与计算机学院 主要内容 v4 1 软件文档管理指南 v4 2 软件文档的编写原则 v4 3 制定文档的编写策略 v4 4建立文档的企业标准 v4 5 制定文档的编制计划 v4 6 建立文档的编制规程 v4 7 软件文档的质量要求 v4 8 软件文档的编写技巧 v4 9 确定软件文档类型的种 类 数学与计算机学院 4 6 制定文档编制规程 文档规程 1 标准 规范 规程的概念 2 文档规程编制特点 3 文档管理规程检查表 4 文档编制规程中规定的实施程序与技术要求 数学与计算机学院 1 标准 规范 规程的概念 v标准 软件工程标准是为在软件工程领域内获得最佳结果规定共同 的和重复使用的规则 导则或特性的文件 该文件经协商一 致制定并经一个公认机构批准 以科学 技术和实践经验的 综合成果为基础 以促进最佳社会效益为目的 v规范 是在工农业生产和工程建设中 对设计 施工 制造 检验 等技术事项所做的一系列规定 v规程 是对作业 安装 鉴定 安全 管理等技术要求
