计算机软件文档编制规范

1、冯辉，GB/T 8567-2006计算机软件文件规范，内容，1修订背景修订摘要文件编制格式根据新旧版本标准结构文件编制流程的不同，1。本标准修订的背景，是参照一家英国公司的文件标准，结合当时国内软件开发经验，主要针对瀑布模型的开发方法而制定的。该标准的发布和实施对我国80年代和90年代的软件发展起到了重要作用。然而，随着软件工程技术的发展和完善，目前版本已经不适应软件产业发展的需要，因此版本修订势在必行。第二，GB/T8567-2006的依据主要是基于：信息技术软件生命周期过程软件开发和文档化：信息技术软件用户文档化过程；第三，新旧版本的主要区别，主要适用于瀑布模型开发方法，并给出了文档的格式

2、要求：)可行性研究报告)项目开发计划)软件需求规格说明，新旧版本的主要区别， )数据需求规格说明)概要设计规格说明)详细设计规格说明)数据库设计规格说明)用户手册)模块开发文件)测试计划)测试分析报告)开发进度月报)项目开发总结报告，新旧版本的主要区别，6。原则上，它适用于各种类型的开发方法。6.它描述了文档准备过程。6.它给出了各种文档的格式要求。6.可行性分析(研究)报告。软件开发计划。软件测试计划。软件安装计划。新旧版本的主要区别。)软件移交计划)操作概念描述)系统子系统需求规格)接口需求规格)系统子系统设计(结构设计)规格)接口设计规格)软件需求规格)数据需求规格)软件(结构)设计规格

3、，新旧版本之间的主要差异)数据库(顶层)设计描述)软件测试描述)软件测试报告)软件配置管理计划)软件质量保证计划)开发进度月报)项目开发总结报告，新旧版本之间的主要差异)软件产品规格)软件版本描述)软件用户手册)计算机操作手册)计算机编程手册)也给出了编译格式要求标准结构、范围、规范性参考文件、术语和定义、缩写、文件(编译)过程、文件编译要求、文件编译格式附录面向对象软件的文件编译、五、文件(编译)过程5.1概述标准主要有两种类型：a .产品标准，规定产品特性和功能要求；b过程标准，规定了开发产品的过程。应用程序和计算机软件的日益复杂使得向用户提供完整、正确和可理解的文档变得更加迫切。该标准通

4、过指定影响软件文档质量的活动(做什么和由谁来做)来提供实现这些目标的工具。文档通常关注软件实现后要做什么。然而，为了质量，软件文档应该是整个软件生产过程的一部分。文件计划应包含在工艺计划中。该标准还为用户和客户提供了工具，以确保文档流程的实施。本标准的主要活动之一是为开发文档建立一个广泛的计划。这是必要的，因为有了计划，文档的质量会更好，过程的效率也会更高。为了符合这一标准，该计划必须包括风格规格。本标准没有规定样式规范的内容(即没有规定具体的布局和字体)，但规定了样式规范必须涵盖的内容。该标准还规定了哪些信息可供文档经理使用，以及谁将审查和复制文档。5.2文件(编制)过程的重点、文件编制计划

5、、文件开发(编制)、文件评审、5.3文件计划、5.3.1摘要文件经理应准备一份文件计划，该计划规定了文件的质量文件计划应正式描述计划文件的范围和限制，以及重要的文件分析和设计决策。还应规定在文档开发过程中实施的程序和控制。文件计划应包括(但不限于)以下内容：a)计划文件的工作名称、目的、范围和限制。b)文件的预期读者和使用目的。c)包含估计页数和其他媒体同等详细信息的文件目录草案。d)交付：打印件数、是否提供电子版、磁盘和文件格式(包括软件版本)以及交付地点。e)版权和任何其他所有权的所有者。这是一个复杂的问题，应该在合同中规定。f)适当时，包括每份文件的安全或保密级别。g)管理文档开发过程的

6、步骤和控制，包括存储、检索、备份、处理和质量保证(如果需要)。h)使用的生产方法、工具和工具版本。I)文档开发人员所在团队的结构，可选地包括团队选择计划。处于不同文档编写和制作阶段的工人需要不同的技能。作者可能需要对正在编写的系统有很好的了解，并有编写文档的经验；编辑可能需要编辑经验，但不需要系统知识；除了所使用的布局工具，布局艺术家可能没有任何知识要求。j)项目依赖性。要求的工时和成本。l)项目资源要求，包括买方提供的信息和其他资源。m)在软件开发过程中，软件改变了向文档管理器传输信息的方法。n)文件变更控制和维护计划(可选)。o)实施后审查计划(可选)。p)显示适当的里程碑时间表，包括：1

7、)文件计划批准；文件中的每一项都应该重复。l文件计划应2)准备、审查和修正每份草稿；3)可用性测试；4)印刷、装订和出版。如果合适的话，这些活动中的每一项都应在文件编制前准备和批准，以确保所有部门都同意所使用的目标和方法。批准后，计划应尽可能广泛地分发；分发应包括所有文件开发商，可能包括买方人员和分包商。5.3.2文件计划控制正式批准后，文件经理应控制文件计划及其发布。文件经理应保存一份文件计划副本的分发清单。如果文件计划将来发生变更(经文件经理和买方同意)，文件经理应确保所有获得文件计划副本的人员都应得到变更通知。由于计划的过期副本可能会导致问题，文件经理应禁止计划的失控副本，并建立审核流程

8、，确保计划的所有副本都已更新。5.4、文件开发，根据文件计划进行文件开发。通常，在文档开发之前，应该指定文档的格式(样式)。这些文档是软件开发和管理过程中需要的，下面描述了每个文档的规范。5.5评审和5.5.1总结本节规定的文件评审的要求和相关活动。本节主要以用户文档的审查为例。开发文件的评审应由供应商组织实施。批准由开发组织的上级技术组织实施。应更加重视定期、非正式和务实的评估。这与形式无关。用户文件的审查应由买方实施，包括必要时与文件经理讨论。评审的目的是确保提交的材料完整、正确，并满足合同和文件计划中规定的需求方的需求。审查应由适当的合格人员进行，这些人员有权要求变更并批准文件的内容。买

9、方应将审核人员的数量限制在审核职能所必需的范围内。在批准每个用户的文件草案之前，买方应确保文件的安全性和合法性。交付审查的文件应包括文件经理的指示，说明审查的目的和审查人员的责任。注1:在整个过程中保持需求方和文件经理之间的良好沟通这应包括非正式讨论，并尽快向需求方提供样品或初始材料。l注2:当要求的变更超出合同和文件计划的范围时，合同需要变更。注意3:审核过程并不能免除文档经理的责任，他们的职责是尽可能确保文档的准确性和完整性。注4:需方对评估结果的意见应写在有标记的草稿中或有适当的参考。买方应保留一份变更副本，以便与下一份草案进行比较。注释应该使文档开发人员能够实现所需的更改，而无需审阅者

10、的进一步解释。注意5:对于大而复杂的系统或在文档编写时仍在开发中的系统，可能需要两个以上的草稿和一个证明。在这种情况下，草稿的最大数量应由买方和文档经理商定，并在文档计划中指定。5.5.2文件计划的评审本次评审的目的应该是确保文件计划中定义的文件在完成时不仅满足开发过程的需要，而且满足买方在合同中规定的文件目标。买方同意文件计划，即同意计划中定义的用户文件的所有可交付功能。注：买方应注意目录草案中显示的文件的结构、完整性和可用性。在适当的时候，文件计划应该在第一稿开始工作之前进行审查和批准。5.5.3初稿的审查初稿应包含文件计划中描述的文件正文，以及目录、附录和词汇表。使用自动索引工具时，生成

11、的索引包含位置引用。标点符号、样式和布局应符合文件计划中的描述。审查文件初稿的目的是检查文件的技术正确性和完整性，以确保草稿符合文件计划的目标。标点符号、风格和布局应符合文件计划的规定。在批准初稿时，除了要求的修改外，还要审查和批准技术正确性、结构清晰性和文件完整性。注1:初稿应在交付前进行编辑。这样做有两个原因：a)这确保了审阅者不会分心去纠正打印和布局错误；确保由编辑过程引起的任何技术错误被审核者捕获。注释2:应根据文档计划中批准的目标、读者定义、目录和其他特征对草稿进行审查。在退回附有意见的初稿之前，应确认如果草稿被完全纠正，它将满足文件计划的要求。5.5.4第二稿的审查第二稿应包括第一

12、稿审查中同意的所有变更，并应包括文件计划中定义的尽可能接近最终形式的可交付成果。本次审查的目的是验证初稿中的内容已正确实施。在批准第二稿时，除了草案的物理形式之外，文件的所有方面都得到批准。草稿的物理形式可能与交付内容的不准确性相同。注：在批准第二稿之前，最好确认草案(包括对草案的审查意见)已准备就绪，可以批准。6.文档要求6.1软件生命周期和各种文档的编译在计算机软件的生命周期中，一般来说，应该生成以下基本文档。可行性分析(研究)报告；软件(或项目)开发计划；软件需求规范；接口要求的规范；系统子系统设计描述(结构设计)；软件(结构)设计说明；界面设计说明；数据库(顶层)设计描述；(软件)用户

13、手册；操作手册；测试计划；测试报告；软件配置管理计划；软件质量保证计划；月度发展进度报告；项目开发总结报告；软件产品规格；软件版本描述等。本标准将给出这些文件的编制标准，同时，本标准也是这些文件编制质量的检验标准。一般来说，软件总是计算机系统(包括硬件、固件和软件)不可或缺的一部分。鉴于计算机系统的多样性，该标准通常不涉及整个系统中的文档对于那些使用文档的人来说，他们关心的文档类型因他们所从事的工作而异。管理人员：可行性分析(研究)报告、项目开发计划、软件配置管理计划、软件质量保证计划、月度开发进度报告和项目开发总结报告；开发者：可行性分析(研究)报告、项目开发计划、软件需求规范、接口需求规范

14、、软件(结构)设计规范、接口设计规范、数据库(顶层)设计规范、测试计划和测试报告；维护人员：软件需求规范、接口需求规范、软件(结构)设计规范、测试报告、用户：软件产品规范、软件版本规范、用户手册和操作手册。本标准规定了软件开发过程中文档的要求。这些文档可以分为两类：用户文档和开发文档。其中，用户文档必须交给用户。用户应获得的文件的类型和大小由供应商和用户之间签订的合同规定。如上所述，软件被认为是软件的生命周期，从一个想法出现的那一天开始，在被软件开发成功地投入使用之后，直到最终决定停止使用并被另一个软件取代。一般来说，这个软件生命周期可以分为以下六个阶段：(1)可行性和规划研究阶段；需求分析阶

15、段；设计阶段；实施阶段；测试阶段；操作和维护阶段。在可行性分析(研究)和规划阶段，需要确定软件的开发目标和总体要求，进行可行性分析、投资收益分析，制定开发计划，并完成需要编制的文件。在需求分析阶段，系统分析员系统地分析所设计的系统，确定软件的功能、性能要求和设计约束，并确定对文档的要求。作为这一阶段工作的结果，一般来说，应该编写软件需求规格说明(也称为软件需求规格说明、软件规格说明)、数据需求规格说明和初步用户手册。在设计阶段，系统设计者和程序员应该在反复理解软件需求的基础上提出多个设计，分析和比较每个设计可以执行的功能，最后确定一个设计，包括软件的结构、模块的划分(或CSCI)、功能的分布和

16、处理流程。当设计的系统复杂时，设计阶段应分为两个步骤：概要设计阶段和详细设计阶段。一般来说，要完成的文件包括结构设计说明、详细设计说明和测试计划初稿。在实施阶段，有必要完成源程序的编码、编译(或汇编)和调试，以获得无语法错误的程序列表，并开始编写日、周、月进度报告(是否有日或周进度报告取决于项目的重要性和规模)，完成用户手册和操作手册等面向用户的文档的编写，并完成测试计划的编制。在测试阶段：将对程序进行全面测试，并对准备好的文件进行检查和评审。通常，应完成测试分析报告。在开发工作结束时，将对所产生的程序、文件和开发工作进行逐项评估，最后编写项目开发总结报告。在整个开发过程中(也就是说，在前五个

17、阶段)，开发团队应该准备每月的开发进度报告。在运行和维护阶段，软件将在运行和使用中不断得到维护，并根据新的要求进行必要和可能的扩展、删除、更新和升级。6.2文件准备中的注意事项。文档准备是开发过程的有机组成部分，是持续努力的工作过程。这是一个完整的过程，从最初的大纲形成、反复检查和修改到正式交付程序和文件。它的每一步都需要员工的巨大努力。为了保证文档的质量，为了反映每个开发项目的特点，我们还应该注意不要花费太多的人力。因此，应考虑以下因素6.2.1文件的读者每个文件都有一个特定的读者。这些读者包括个人或团体、软件开发单位成员或公众、从事软件工作的技术人员、经理或领导干部。他们希望将这些文档的内容用于工作，例如设计、