计算机软件文档编制规范摘要

目录

• 缩略语
• 文档过程
• 文档编制要求
  • 软件生存周期与各种文档的编制
  • 文档编制中的考虑因素
    • 文档的读者
    • 重复性
    • 灵活性
• 附录：文档链接

本标准原则上适用于所有类型的软件产品的开发过程和管理过程。
使用者可根据实际情况对本标准进行适当剪裁(可剪裁所需的文档类型,也可对规范的内容作适当裁剪)。
软件文档从使用的角度大致可分为软件的用户需要的用户文档和开发方在开发过程中使用的内部文档(开发文档)两类。供方应提供的文档的类型和规模，由软件的需方和供方在合同中规定。

缩略语

缩略	中文全称	英文全称
CASE	计算机辅助软件工程	Computer Assistant Software Engineering
COM	计算机操作手册	Computer Operation Manual
CPM	计算机编程手册	Computer Programming Manual
CSCI	计算机软件配置项	Computer Software Configuration Item
DBDD	数据库(顶层)设计说明	Database Design Description
DID	资料条目说明	Data Item Description
DPMR	开发进度月报	Development Plan Month Report
DRD	数据需求说明	Data requirement Description
FAR	可行性分析报告	Feasibility analysis Report
HWCI	硬件配置项	Hardware Configuration Item
IDD	接口设计说明	Interface Design Description
IRS	接口(软件)需求规格说明	Interface Requirement Specification
IV&V	独立验证和确认	Independent verification and validation
OCD	运行概念说明	Operation Conception Description
PDSR	项目开发总结报告	Project Development summary Report
SCCB	软件配置控制委员会	Software Configuration Control Board
SCM	软件配置管理	Software Configuration Manager
SCMP	软件配置管理计划	Software Configuration Manager Plan
SDD	软件(结构)设计说明	Software Design Description
SDF	软件开发文件	Software Development File
SFDD	软件开发文档	Software Development Document
SDL	软件开发库	Software Development Library
SDP	软件开发计划	Software Development Plan
SIP	软件安装计划	Software Installation Plan
SPS	软件产品规格说明	Software Product Specification
SQA	软件质量保证	Software Quality Assure
SQAP	软件质量保证计划	Software Quality Assure Plan
SRS	软件需求规格说明	Software Requirement Specification
SSDD	系统/子系统设计(结构设计)说明	System Subsystem Design Description
SSS	系统/子系统需求规格说明	System Subsystem Requirement Specification
STD	软件测试说明	Software Testing Descrition
STP	软件测试计划	Software Testing Plan
STR	软件测试报告	Software Testing Report
STrP	软件移交计划	Software Transfer Plan
SUM	软件用户手册	Software User Manual
SVD	软件版本说明	Software Version Description
SW	软件	Software

文档过程

有两种主要类型的标准：

• 产品标准：它规定产品的特征和功能需求。
• 过程标准：它规定开发产品的过程。

应用程序和计算机软件的复杂性日益增加，使得给使用计算机的用户提供完整的、正确的和易懂的文档的需要更加迫切。
文档常常是关心在软件已经实现后做些什么。然而，为了质量，软件文档编制应作为整个软件生产过程的一部分。

文档过程的活动应按下图中的顺序执行：

其中，有两个阴影框。在一个阴影框中的所有活动应在下一个阴影框中的活动开始之前完成。在阴影框中的活动可以并行执行。虚线指示可能的重复。

文档编制要求

软件生存周期与各种文档的编制

在软件的生存周期中，一般地说，应该产生以下一些基本文档：

• a)可行性分析(研究)报告
• b)软件(或项目)开发计划
• c)软件需求规格说明
• d)接口需求规格说明
• e)系统/子系统设计(结构设计)说明
• f)软件(结构)设计说明
• g)接口设计说明
• h)数据库(顶层)设计说明
• i)(软件)用户手册
• j)操作手册
• k)测试计划
• 1)测试报告
• m)软件配置管理计划
• n)软件质量保证计划
• o)开发进度月报
• p)项目开发总结报告
• q)软件产品规格说明
• r)软件版本说明等

对于使用文档的人员而言，他们所关心的文件的种类随他们所承担的工作而异：

管理人员	开发人员	维护人员	用 户
可行性分析(研究)报告 项目开发计划 软件配置管理计划 软件质量保证计划 开发进度月报 项目开发总结报告	可行性分析(研究)报告 项目开发计划 软件需求规格说明 接口需求规格说明 软件(结构)设计说明 接口设计说明书 数据库(顶层)设计说明 测试计划 测试报告	软件需求规格说明 接口需求规格说明 软件(结构)设计说明 测试报告	软件产品规格说明 软件版本说明 用户手册 操作手

这些文档从使用的角度可分为用户文档和开发文档两大类。其中，用户文档必须交给用户。用户应该得到的文档的种类和规模由供应者与用户之间签订的合同规定。

如前所述，软件，从出现一个构思之日起，经过软件开发成功投入使用，直到最后决定停止使用并被另一项软件代替之时止，被认为是该软件的一个生存周期，一般地说这个软件生存周期可以分成以下 6 个阶段：

• a)可行性与计划研究阶段
  在可行性分析(研究)与计划阶段内，要确定该软件的开发目标和总的要求，要进行可行性分析、投资——收益分析、制订开发计划，并完成可行性分析报告、开发计划等文档。

• b)需求分析阶段
  在需求分析阶段内，由系统分析人员对被设计的系统进行系统分析，确定对该软件的各项功能、性能需求和设计约束，确定对文档编制的要求，作为本阶段工作的结果，一般地说软件需求规格说明(也称为：软件需求说明、软件规格说明)、数据要求说明和初步的用户手册应该编写出来。

• c)设计阶段
  在设计阶段内，系统设计人员和程序设计人员应该在反复理解软件需求的基础上，提出多个设计，分析每个设计能履行的功能并进行相互比较，最后确定一个设计，包括该软件的结构、模块(或 CSCI)的划分、功能的分配，以及处理流程。
  在被设计系统比较复杂的情况下，设计阶段应分解成概要设计阶段和详细设计阶段两个步骤。在一般情况下，应完成的文档包括：结构设计说明、详细设计说明和测试计划初稿。

• d)实现阶段
  在实现阶段内，要完成源程序的编码、编译(或汇编)和排错调试得到无语法错的程序清单，要开始编写进度日报、周报和月报(是否要有日报或周报，取决于项目的重要性和规模)，并且要完成用户手册、操作手册等面向用户的文档的编写工作，还要完成测试计划的编制。

• e)测试阶段
  在测试阶段，该程序将被全面地测试，已编制的文档将被检查审阅。一般要完成测试分析报告。作为开发工作的结束，所生产的程序、文档以及开发工作本身将逐项被评价，最后写出项目开发总结报告。

注：在整个开发过程中(即前五个阶段中)，开发集体要按月编写开发进度月报。

• f)运行与维护阶段
  在运行和维护阶段，软件将在运行使用中不断地被维护，根据新提出的需求进行必要而且可能的扩充和删改、更新和升级。

文档编制中的考虑因素

文档的读者

每一种文档都具有特定的读者。这些读者包括个人或小组、软件开发单位的成员或社会上的公众、从事软件工作的技术人员、管理人员或领导干部。他们期待着使用这些文档的内容来进行工作，例如设计、编写程序、测试、使用、维护或进行计划管理。因此这些文档的作者必须了解自己的读者。这些文档的编写必须注意适应自己的特定读者的水平、特点和要求。

重复性

本标准中列出的文档编制规范的内容要求中，显然存在某些重复。较明显的重复有两类。引言是每一种文档都要包含的内容，以向读者提供总的梗概。第二类明显的重复是各种文档中的说明部分，如对功能性能的说明；对输入、输出的描述；系统中包含的设备等。
这是为了方便每种文档各自的读者，每种文档应该自成体系尽量避免读一种文档时又不得不去参考另一种文档。当然，在每一种文档里，有关引言、说明等同其他文档相重复的部分，在行文上、在所用的术语上、在详细的程度上，还是应该有一些差别以适应各种文档的不同读者的需要。

灵活性

鉴于软件开发是具有创造性的脑力劳动，也鉴于不同软件在规模上和复杂程度上差别极大，在文档编制工作中允许一定的灵活性。这种灵活性如下所述。

• a)应编制的文档种类
  一般情况下，一项软件的开发过程中，应产生如上所述的各种文档，然而针对一项具体的软件开发项目，有时不必编制这么多的文档，可以把几种文档合并成一种。
  一般地说，当项目的规模、复杂性和失败风险增大时，文档编制的范围，管理手续和详细程度将随之增加，反之，则可适当减少。

• b)文档的详细程度
  从同一份提纲起草的文件的篇幅大小往往不同，可以少到几页，也可以长达几百页。此详细程度取决于任务的规模、复杂性和项目负责人对该软件的开发过程及运行环境所需要的详细程度的判断。

• c)文档的扩展
  当被开发系统的规模非常大(例如源码超过一百万行)时，一种文档可以分成几卷编写，可以按其中每一个系统分别编制，也可以按内容划分成多卷，例如：
  项目开发计划可能包括：质量保证计划，配置管理计划，用户培训计划，安装实施计划；
  系统设计说明可分写成：系统设计说明，子系统设计说明；
  程序设计说明可分写成：程序设计说明，接口设计说明，版本说明；
  操作手册可分写成：操作手册，安装实施过程；
  测试计划可分写成：测试计划，测试设计说明，测试规程，测试用例；
  测试分析报告可分写成：综合测试报告，验收测试报告；
  项目开发总结报告亦可分写成项目开发总结报告和资源环境统计。

• d)章、条的扩张与缩并
  在软件文档中，一般宜使用本标准提供的章、条标题。但所有的条都可以扩展，可以进一步细分，以适应实际需要。反之如果章条中的有些细节并非必需，也可以根据实际情况缩并。此时章条的编号应相应地变更。

• e)程序设计的表现形式
  本标准对于程序的设计表现形式并未作出规定或限制，可以使用流程图的形式，判定表的形式，也可以使用其他表现形式，如程序设计语言(PDL)、问题分析图(PALb)等。

• f)文档的表现形式
  本标准对于文档的表现形式亦未作出规定或限制。可以使用自然语言，也可以使用形式化语言。也可以使用各种图、表。

• g)文档的其他种类
  当本标准中规定的文档种类尚不能满足某些应用部门的特殊需要时，他们可以建立一些特殊的文档种类要求，例如软件质量保证计划、软件配置管理计划等，这些要求可以包含在本单位的文件编制实施规定中。

附录：文档链接

GB8567-2006《计算机软件文档编制规范》 - 道客巴巴
附录2 GB T-8567-2006计算机软件文档编制案例 - 道客巴巴