软件文档编写规范

1、软件文档编写规范文件状态： 草稿 正式发布 正在修改产品名称：文件编码：编 撰：李景荣编撰日期：2011年1月19日保密级别：文档版本：通用供应链技术与系统修订表编号生成版本修订人修订章节与内容修订日期10.0.1李景荣初稿2011-01-19234审批记录版本审批人审批意见审批日期目录1 引言12 引用标准13 范围14 文件的使用者25 软件生存周期与各种文件的编制36 文件编制中的注意事项561 文件的读者562 重复性563 灵活性5631 应编制的文件种类6632 文件的详细程度6633 文件的扩展6图表索引图 1 用户对文件的需求8图 2 软件生存周期8表 1 软件生存周期各阶段内

2、编制的文档91 引言软件文档(document)也称文件，通常指的是一些记录的数据 和数据媒体，它具有固定不变的形式，可被人和计算机阅读。它和计算机程序共同构成了能完成特定功能的计算机软件。软件文档的编制(documentation)在软件开发工作中占有突 出的地位和相当的工作量。高效率、高质量地开发、分发、管理和维 护文档对于转让、变更、修正、扩充和使用文档，对于充分发挥软件产品的效益有着重要意义。本文参照GB-T8567-2006计算机软件文档编制规范制定此软件开发文档编制规范，供通用供应链技术与系统公司（GSCT）软件研发使用。2 引用标准GB-T8567-2006计算机软件文档编制规范

3、GB/T11457-2006 中华人民共和国国家标准：信息技术 软件工程术语3 范围一项软件的开发周期中，一般地说，应该产生十四种文件。这十四种文件是：   可行性研究报告；   项目开发计划；   软件需求说明书；   数据要求说明书；   概要设计说明书；   详细设计说明书；   数据库设计说明书；   用户手册；   操作手册；   模块开发卷宗；   测试计划；

4、60;  测试分析报告；   开发进度月报；    项目开发总结报告。以上14种文件是针对一般性的软件开发所建议应该生成的文档，可以根据软件项目的规模适当的增加或者合并软件的文档。根据GSCT的特性，还有三种文档：项目会议纪要：主要是项目组核心成员关于项目内容讨论的会议纪要。软件功能修改申请：项目交付用户使用后，由于业务需求的变化需要修改软件内容时，业务相关人员必须提交修改申请，经相关的负责人员批准通过后，交予软件项目负责人。软件负责人接到软件修改申请后，评估修改的工作量和会对软件产生的影响，将申请转化为具体的修改需求。软件功能修改报告：软件项

5、目负责人通过对修改申请的评估，将申请转化为具体的修改需求，提交给开发人员对软件功能进行修改。 4 文件的使用者 不同的使用人员，随他们所承担的工作的不同，对文档的需求也会有所不同。如图1所示。 可行性研究报告 项目开发计划 管理人员 模块开发卷宗 开发进度月报项目会议纪要              项目开发总结报告 可行性研究报告，项目会议纪要         

6、60;    项目开发计划              软件需求说明书              数据要求说明书            概要设计说明书     &

7、#160;        开发人员 详细设计说明书              数据库设计说明书，              测试计划，           &#

8、160;  测试分析报告； 扩充修改申请 修改报告用户 操作手册 用户手册图 1 用户对文件的需求以上文档是对软件开发过程中所产生文档的使用建议。用户应该得到的文件的种类由供应者与用户之间签订的合同规定。5 软件生存周期与各种文件的编制一项计算机软件，从出现一个构思之日起，经过这项软件开发成功投入使用，直到最后决定停止使用，并被另一项软件代替之时止，被认为是该软件的一个生存周期。一般地说这个软件生存周期可以分成以下六个阶段，如图2 所示：图 2 软件生存周期各个阶段的工作简介如下：   可行性研究与计划阶段：确定该软件的开发目标和总的要求，进行可行性分析、投资-收

9、益分析、制订开发计划，并完成应编制的文件。需求分析阶段：由系统分析人员对被设计的系统进行系统分析，确定对该软件的各项功能、性能需求和设计约束，确定对文件编制的要求，作为本阶段工作的结果，一般地说，软件需求说明书、数据要求说明书和初步的用户手册应该编写出来。   设计阶段：系统设计人员和程序设计人员在反复理解软件需求的基础上，提出多个设计，分析每个设计能履行的功能并进行相互比较，最后确定一个设计，包括该软件的结构、模块的划分、功能的分配以及处理流程。在被设计系统比较复杂的情况下，设计阶段应分解成概要设计阶段和详细设计阶段两个步骤。在一般情况下，应完成的文件包括：概要设计说明书

10、、详细设计说明书和测试计划初稿。   编码实现阶段：完成源程序的编码、编译（或汇编）和排错调试得到无语法错误的程序清单，要开始编写模块开发卷宗，并且要完成用户手册、操作手册等面向用户的文件的编写工作，还要完成测试计划的编制。   测试阶段：该程序将被全面地测试，已编制的文件将被检查审阅。一般要完成模块开发卷宗和测试分析报告，作为开发工作的结束，所生产的程序、文件以及开发工作本身将逐项被评价，最后写出项目开发总结报告。   在整个开发过程中（即前五个阶段中），开发集体要按月编写开发进度月报。   在运行和维护阶段：软

11、件将在运行使用中不断地被维护，根据新提出的需求进行必要而且可能的扩充和删改。   对于一项软件而言，其生存周期各阶段与各种文件编写工作的关系可见表1，其中有些文件的编写工作可能要在若干个阶段中延续进行。 阶段文档        可行性研究与计划需求分析设计编码实现测试运行与维护可行性研究报告      项目开发计划      项目会议纪要软件需求说明  &#

12、160;   数据要求说明      概要设计说明      详细设计说明      数据库设计说明书测试计划      模块开发卷宗用户手册      操作手册      测试分析报告  

13、    开发进度月报      项目开发总结      软件功能修改申请软件功能修改报告表 1 软件生存周期各阶段内编制的文档6 文件编制中的注意事项   文件编制是一个从形成最初轮廓，经反复检查和修改，直到程序和文件正式交付使用的完整过程。要保证文件编制的质量，体现每个开发项目的特点，编制中要注意以下几点。61 文件的读者每一种文件都具有特定的读者。这些读者包括个人或小组、软件开发成员或其他的管理人员、领导干部或用

14、户。他们期待着使用这些文件的内容来进行工作，例如设计、编写程序、测试、使用、维护或进行计划管理。因此，软件文档的编制者在编制文档时，必须考虑文档的使用者的水平、特点和要求。 62 重复性本规范中列出的这十七种文件的内容要求中，在文件内容上存在重复。这是为了方便每种文件各自的读者，每种产品文件应该自成体系，避免读一种文件时又不得不去参考另一种文件。当然，在每一种文件里，有关引言、说明等同其他文件相重复的部分，在行文上、在所用的术语上、在详细的程度上，还是应该有一些差别，以适应各种文件的不同读者的需要。63 灵活性鉴于不同的软件在规模和复杂程度上有很大差别，因此软件文档的编写也存在着一定的灵活性。

15、631 应编制的文件种类 针对一项具体的软件开发项目，需要编制的文档的种类由软件项目的规模和复杂性决定。对于规模比较小的简单的项目，可以把几种文件合并成一种。一般地说，当项目的规模、复杂性和成败风险增大时，文件编制的范围、管理手续和详细程度将随之增加。反之，则可适当减少。对于一个具体的应用软件项目，项目负责人应制定一个文件编制计划，其中包括:  （1）应该编制哪几种文件，详细程度如何？  （2）各个文件的编制负责人和进度要求；  （3）审查、批准的负责人和时间进度安排；   （4）在开发时期内，各文件的维护、修改和管理的负责人，以及批准手续。  

16、; 每项工作必须落实到人。文件编制计划是整个开发计划的重要组成部分，有关的设计人员则必须严格执行这个文件编制计划。632 文件的详细程度文件详细程度取决于任务的规模、复杂性和项目负责人对该软件的开发过程及运行环与所需要的详细程度的判断。633 文件的扩展 当被开发系统的规模非常大（例如源码超过一百万行）时，一种文件可以按内容分成多卷编写，也可按照功能进行细分。例如：   项目开发计划可划分为：质量保证计划，              &

17、#160;          配置管理计划，                         用户培训计划，             

18、60;           安装实施计划；   系统设计说明书可划分为：系统设计说明书，                           子系统设计说明书；   程序设计说明书可划分为：程序设计说

19、明书，                           接口设计说明书，                           版本说明；   操作手册可划分为：操作手册，                 &#