软件文档国家标准与写作要求

1、浙江工业大学计算机学院 陆佳炜第三章 软件文档国家标准软件文档写作主要内容软件产品开发文档编制指南 软件需求说明编制指南软件测试文档编制规范软件文档管理指南1、软件产品开发文档编制指南 软件文档国家标准 计算机软件产品开发文档编制指南 （GB 8567-1988） 计算机软件需求说明编制指南 （GB 9385-1988） 计算机软件测试文档编制规范 （GB 9386-1988） 软件文档管理指南 （GB 16680-1996）2006年后计算机软件产品开发文件编制指南（GBT8567-2006）计算机软件测试文件编制规范（GBT9386-2008）软件产品开发文件编制指南 计算机软件产品开发文

2、档编制指南是一份指导性文档，目的是使得所编制的软件文档确实能够起到应该发挥的作用。指南对软件文档的意义和作用、文档与读者的关系、软件生存周期与各种文档的编制、文档编制中的考虑因素、文档编制的管理工作以及各种文档的内容要求都作了详细描述，并给出了各类文档的编写提示。 软件产品开发文件编制指南 根据该指南，一项计算机软件的开发过程中，一般应产生如下十四种文档：（1）可行性研究报告（2）项目开发计划（3）软件需求说明书（4）数据要求说明书（5）概要设计说明书（6）详细设计说明书（7）数据库设计说明书（8）用户手册（9）操作手册（10）模块开发卷宗（11）测试计划（12）测试分析报告（13）开发进度月

3、报（14）项目开发总结报告 本指南不仅给出了这十四种文档的编制指导，同时，本指南也是这十四种文档编写质量的检验准则。2、软件需求说明编制指南软件需求说明编制指南 软件需求说明编制指南 软件需求说明编制指南 软件需求说明编制指南 软件需求说明编制指南为软件需求的实践提供了一个规范化的方法，主要描述了软件需求说明（Software Requirements Specifications，简称SRS）所必须的内容和质量。 软件需求文档的编制目标 SRS对于软件客户来讲，应尽可能准确地描述其所需要的产品；而对于软件开发者，应能准确地理解客户所需要的产品。 编制SRS的目标可以概括为如下六个方面： （1

4、）在软件产品完成目标方面为客户和开发者之间建立共同协议创立一个基础 （2）提高开发效率 （3）为成本计价和编制计划进度提供基础 （4）为确认和验证提供一个基准 （5）便于移植 （6）作为不断提高的基础软件需求文档的基本要求 SRS是对要完成一定功能、性能的软件产品、程序或一组程序的说明。因此对SRS的描述有两项基本要求： （1）必须描述一定的功能、性能； （2）必须用确定的方法叙述这些功能、性能。 SRS作为软件开发规范之一，对软件开发的所有阶段都起着非常重要的作用，但是需要注意的是，SRS不能超出其作用范围，即除了SRS正确地定义所有软件的需求之外，一般地SRS不描述任何设计、验证或项目管理

5、的细节。 软件需求标准适用范围 1. 指南适用对象 软件客户（Customers），以便精确地描述他们想获得什么样的产品。 软件开发者（Suppliers），以便准确地理解客户需要什么样的产品。 2. 指南目的 对于任一单位和（或）个人，要实现下列目标： a. 要提出开发规范化的SRS提纲； b. 定义自己需要的具体的格式和内容； c.产生附加的局部使用条款，如SRS质量检查清单或者SRS作者手册等。3、软件测试文档编制规范软件测试文档编制规范 测试是软件生存周期中一个独立的、关键的阶段，也是保证软件质量的重要手段。为了提高检测出错误的几率，使测试能有计划地、有条不紊地进行，就必须要编制测试文

6、档。而标准化的测试文档就如同一种通用的参照体系，可达到便于交流的目的。计算机软件测试文档编制规范的目的就是规定一组软件测试文档，定义每一种基本文档的目的、格式和内容。测试文档中所规定的内容可以作为对测试过程完备性的对照检查表，这将会提高测试过程的每个阶段的能见度，极大地提高测试工作的可管理性。 软件测试文档内容 计算机软件测试文档编制规范主要定义了三种类型软件测试文档：测试计划测试说明测试报告测试计划 测试计划描述测试活动的范围、方法、资源和进度。它规定被测试的项、被测试的特性、应完成的测试任务、担任各项工作的人员职责及与本计划有关的风险等测试说明 测试说明包括三个文档： （1）测试设计说明详

7、细描述测试方法，规定该设计及其有关测试所包括的特性(功能、性能、可移植性等)，还规定完成测试所需的测试用例和测试规程，并规定特性的通过准则。（2）测试用例说明列出用于输入的具体值以及预期的输出结果，并规定在使用具体测试用例时，对测试规程的各种限制。将测试用例与测试设计分开，可以使它们用于多个设计并能在其它情形下重复使用。（3）测试规程说明规定对于运行系统和执行指定的测试用例来实现有关测试设计所要求的所有步骤。 测试报告 测试报告包括四类文档： （1）测试项传递报告所谓的测试项是指作为测试对象的软件项（源代码、目标代码、作业控制代码、数据等），该报告指明在开发组和测试组独立工作的情况下或者在希望

8、正式开始测试的情况下为进行测试而被传递的测试项。（2）测试日志测试组用于记录测试执行过程中发生的情况。（3）测试事件报告描述在测试执行期间发生并需进一步调查的一切事件。（4）测试总结报告总结与测试设计说明有关的测试活动。测试文档的结构 软件测试文档的内容主要包括：测试计划测试设计说明测试用例说明测试规程说明测试项传递报告测试日志测试事件报告以及测试总结报告1、测试计划 1 测试计划名称 2 引言 3 测试项 4 被测试的特性 5 不被测试的特性 6 方法 7 项通过准则 8 暂停标准和再启动要求 9 应提供的测试文件 10 测试任务 11 环境要求 12 职责13 人员和训练要求 14 进度

9、15 风险和应急 16 批准 2、测试设计说明 1 测试设计说明名称 2 被测试的特性 3 方法详述 4 测试用例名称 5 特性通过准则 1 测试用例说明名称 2 测试项 3 输入说明 4 输出说明 5 环境要求 6 特殊的规程说明7 用例间的依赖关系 3、测试用例说明4、测试规程说明 5、测试项传递报告6、测试日志7、测试事件报告1 测试规程说明名称 2 目的 3 特殊要求 4 规程步骤 1 传递报告名称 2 传递项 3 位置 4 状态 5 批准 1 测试日志名称 2 描述 3 活动和事件条目 1 测试事件报告名称 2 摘要 3 事件描述 4 影响 8、测试总结报告 1 测试总结报告名称2

10、简述3 差异4 测试充分性评价5 结果概述6 评价7 活动总结8 批准测试文档的编制 软件测试文档的内容主要包括测试计划、测试设计说明、测试用例说明、测试规程说明、测试项传递报告、测试日志、测试事件报告以及测试总结报告八项内容。需要强调，软件测试包括对需求说明书的测试，因此，在软件的需求分析阶段，就应开始测试文档的编制工作，各种测试文档的编写应按一定的格式进行测试文档的编制 1. 设计测试用例 测试用例（Test Case）是指对一项特定的软件产品进行测试任务的描述，体现测试方案、方法、技术和策略。内容包括测试目标、测试环境、输入数据、测试步骤、预期结果、测试脚本等，并形成文档2. 编写测试文

11、档 测试文档主要由若干测试用例组成，各种测试文档的编写应有文档模板，按一定的格式进行。 测试文档由简介和测试用例两部分组成。简介部分编制了测试目的、测试范围、定义术语、参考文档、概述等。测试用例部分逐一列示各测试用例。每个具体测试用例都将包括下列详细信息：用例编号、用例名称、测试等级、入口准则、验证步骤、期望结果（含判断标准）、出口准则、注释等。以上内容涵盖了测试用例的基本元素：测试索引，测试环境，测试输入，测试操作，预期结果，评价标准。测试文档的编制 实例 文件活动测试计划测试设计说明测试用例说明测试规程说明测试项传递报告测试日志测试事件报告测试总结报告验收-安装-系统子系统-模块-4、软件

12、文档管理指南软件文档管理指南 软件文档管理指南是为那些对软件或基于软件的产品的开发负有职责的管理者提供软件文档的管理指南。其目的在于协助管理者在他们的机构中产生有效的文档。（1）软件文档管理涉及策略、标准、规程、资源和计划，管理者必须关注这些内容，以便有效地管理软件文档。 （2）软件文档管理期望应用于各种类型的软件，从简单的程序到复杂的软件系统。并期望覆盖各种类型的软件文档，作用于软件生存期的各个阶段。 （3）不论项目的大小，软件文档管理的原则是一致的。对于小项目，可以不采用本标准中规定的有关细节。管理者可剪裁这些内容以满足他们的特殊需要。（4）软件文档管理是针对文档编制管理而提出的，不涉及软

13、件文档的内容和编排。浙江工业大学计算机学院 陆佳炜第四章 软件文档写作要求软件文档写作主要内容软件文档的编写原则 制定文档的编写策略 软件文档的质量等级 制定文档的编制计划 建立文档的编制规程 软件文档的质量要求 软件文档的编写技巧 确定软件文档类型的种类1、软件文档的编写原则 软件文档的编写原则 文档编制的原则文档编写应适应文档的读者文档编写应有必要的重复性文档编写应具有一定灵活性文档种类文档详细程度文档的扩展章节的扩张与缩并程序设计的表现形式文档的表现形式 文档其他种类软件文档的编写原则 文档编制的原则文档编写应适应文档的读者文档编写应有必要的重复性文档编写应具有一定灵活性文档种类文档详细

14、程度文档的扩展章节的扩张与缩并程序设计的表现形式文档的表现形式 文档其他种类软件文档的编写原则 根据一个项目的规模、复杂性和成败风险，决定应编制的文档种类及其详细当被开发的项目规模非常大时，可以将一个文档拆分成多个卷进行编制。项目开发计划可能包括： 质量保证计划； 配置管理计划； 用户培训计划； 安装实施计划。系统设计说明书可分写成： 系统设计说明书； 子系统设计说明书。程序设计说明书可分写成： 程序设计说明书； 接口设计说明书； 版本说明。 软件文档的编写原则 所有的章节都可以进一步细分或缩并，以适应实际需要。程序的设计表现形式可以使用多种形式，如流程图、判定表、等其他表现形式。按规定：重量

15、不超过30公斤的行李可免费托运。重量超过30公斤时，对超运部分，头等舱国内乘客收4元/公斤；其它舱位国内乘客收6元/公斤；外国乘客收费为国内乘客的2倍；残疾乘客的收费为正常乘客的1/2。 软件文档的编写原则 2、制定文档的编写策略 制定文档的编写策略 文档策略是由上级（资深）管理者提出并支持的，对下级开发单位或开发人员提供指导。策略规定主要的方向，而不是规定做什么或如何做。 文档需要覆盖整个软件生存期 文档应是可管理的文档应适合于它的读者文档效应应贯穿到软件的整个开发过程中文档标准应被标识和使用 应规定支持工具文档策略制定文档的编写策略 评估现有策略条款的有效性和完整性的文档检查表适当的文档的

16、决策作出了吗？涉及文档的策略声明发布了吗？负责开发文档和产品文档编写工作的人员或部门落实了吗？用于文档编制的资源落实了吗？负责文档质量的人员或部门落实了吗？各管理层次和组织各分支之间的各种关系确定了吗？对于文档的编制、分发和维护等方面是否确定了职责、所需活动和联系途径？所有的文档要求已列入整个项目开发计划表中了吗？适用的文档标准已确定了吗？是否已考虑采用支持工具和自动化的文档编制？ 3、软件文档的质量等级 软件文档的质量等级 是不是每个人编写的文档质量都一样？如何确定文档的质量？如何保证？评价文档的质量主要从两个方面： 文档的结构：其质量从各个组成部分的顺序和总体安排的简单性来测定。 文档的内

17、容：从文档内容的正确性、完整性和明确性来判断。软件文档的质量等级 文档的质量可以按文档的形式和要求划分为四级：（1）最低限度文档（1级文档）：1级文档适合开发工作量低于一个人月的软件。该文档应包含程序清单、开发记录、测试数据和程序简介。（2）内部文档（2级文档）：2级文档可用于在精心研究后被认为没有与其他用户共享资源的专用程序。除1级文档提供的信息外，2级文档还包括程序清单内足够的注释以帮助用户安装和使用程序。（3）工作文档（3级文档）：3级文档适合于由同一单位内若干人联合开发的程序，或可被其他单位使用的程序。（4）正式文档（4级文档）：4级文档适合那些要正式发行供普遍使用的软件产品。关键性程

18、序或具有重复管理应用性质（如工资计算）的程序需要4级文档。4级文档遵守GB 8567的有关规定。 软件文档的质量等级 质量从第1级到第四级，需要的投入和资源逐级增加，质量保证机构必须处于适当的行政地位以保证达到期望的质量等级。 为了保证文档的质量，主要从一下几个方面： 评审鉴定 责任到人 采用制作工具4、制定文档的编制计划制定文档的编制计划 一般包括以下几方面内容： 列出应编制文档的目录；提示编制文档应参考的标准；指定文档管理员；提供编制文档所需要的条件，落实文档编写人员、所需经费以及编制工具等；明确保证文档质量的方法；绘制进度表，以图表形式列出在软件生存期各阶段应产生的文档、编制人员、编制日

19、期、完成日期、评审日期等。 文档计划主要指出未来的活动，每个文档应该达到的质量等级等内容。文档计划检查表 文档计划检查表如下：文档计划编制好了吗？所需的文档类型确定好了吗？所需的内容是否已列提纲并描述了？文档标准确定了吗？文档标准制订好了吗？有关文档编制、文档管理员、备用的文档存储及文档评审的职责分配好了吗？质量准则建立了吗？有关提交草稿概要、初稿、修订稿、图示的计划表是否已建立？评审日期确定了吗？一个认可的周期确定了吗？制作方法是否已选定并作出计划了？ 5、建立文档的编制规程 建立文档的编制规程 文档编制规程提出关于文档的计划、编制、评审、制作和分发的逻辑顺序。这些规程内含审批、质量保证及若

20、干控制点，概述修改步骤、存储和维护要求以及更新方法。 计划制定文档编写文档编号文档评审文档签署 归档保管文档维护编制规程建立文档的编制规程 评审是提供软件产品质量的有效方法。评审的评审点有：需求评审、概要设计评审、详细设计评审和验收。计划制定文档编写文档编号文档评审文档签署 归档保管文档维护编制规程建立文档的编制规程 计划制定文档编写文档编号文档评审文档签署 归档保管文档维护编制规程编写审核会签标准化批准6、软件文档的质量要求软件文档的质量要求 （1）针对性：分清读者、适应需要。（2）精确性：行文确切，避免多义。（3）清晰性：力求简明，运用图表。（4）完整性：自称体系，避免引用。（5）灵活性：大的扩展，小的合并。（6）可追溯性：逐步扩展，前后照应。7、软件文档的编写技巧软件文档的编写技巧 1. 从技术角度进行文档的编写和评价 2. 明确文档编写人员的责任 3. 让