软件方面的文档标准

在文档标准方面，主要有《软件文档管理指南》（GB/T16680-1996）、《计算机软件产品开发文件编制指南》（GB/T8567-2006）和《计算机软件需求说明编制指南》（GB/T9385-2008）等三个标准。1.GB/T16680-1996GB/T16680-1996为那些对软件或基于软件的产品的开发负有职责的管理者提供软件文档的管理指南，目的在于协助管理者在他们的机构中产生有效的文档。该标准涉及策略、标准、规程、资源和计划，管理者必须关注这些内容，以便有效地管理软件文档。根据GB/T16680-1996的规定，文档是指一种数据媒体和其上所记录的数据，它具有一直性并可以由人或机器阅读，通常仅用于描述人工可读的内容，例如，技术文件、设计文件、版本说明文件。软件文档的作用主要体现在管理依据、任务之间联系的凭证、质量保证、培训与参考、软件维护支持、历史档案等方面。软件文档可归入三种类别，分别是开发文档（描述开发过程本身）、产品文档（描述开发过程的产物）和管理文档（记录项目管理的信息）。（1）文档计划文档计划是指一个描述文档编制工作方法的管理用文档。该计划主要描述要编制什么类型的文档，这些文档的内容是什么，何时编写，由谁编写，如何编写，以及什么是影响期望结果的可用资源和外界因素。文档计划一般包括以下方面的内容：√列出应编制文档的目录。√提示编制文档应参考的标准。√指定文档管理员。√提供编制文档所需要的条件，落实文档编写人员、所需经费以及编制工具等。√明确保证文档质量的方法，为了确保文档内容的正确性、合理性，应采取一定的措施，如评审、鉴定等。√绘制进度表，以图表形式列出在软件生存期各阶段应产生的文档、编制人员、编制日期、完成日期、评审日期等。此外，文档计划规定每个文档要达到的质量等级，以及为达到期望结果必须考虑哪些外部因素。文档计划还确定该计划和文档的分发，并且明确叙述参与文档工作的所有人员的职责。（2）开发文档开发文档是描述软件开发过程，包括软件需求、软件设计、软件测试、保证软件质量的一类文档，开发文档也包括软件的详细技术描述（程序逻辑、程序间相互关系、数据格式和存储等）。开发文档起到如下作用：√它们是软件开发过程中包含的所有阶段之间的通信工具，它们记录生成软件需求、设计、编码和测试的详细规定和说明。√它们描述开发小组的职责。通过规定软件、主题事项、文档编制、质量保证人员以及包含在开发过程中任何其他事项的角色来定义做什么、如何做和何时做。√它们用作检验点而允许管理者评定开发进度。如果开发文档丢失、不完整或过时，管理者将失去跟踪和控制软件项目的一个重要工具。√它们形成了维护人员所要求的基本软件文档，而这些支持文档可作为产品文档的一部分；√它们记录软件开发的历史。基本的开发文档有可行性研究和项目任务书；需求规格说明；功能规格说明；设计规格说明，包括程序和数据规格说明；开发计划；软件集成和测试计划；质量保证计划、标准、进度；安全和测试信息。（3）产品文档产品文档规定关于软件产品的使用、维护、增强、转换和传输的信息。产品文档起到如下三种作用：√为使用和运行软件产品的任何人规定培训和参考信息。√使得那些未参加本软件开发的程序员维护它。√促进软件产品的市场流通或提高可接受性。产品文档用于下列类型的读者：√用户。他们利用软件输入数据、检索信息和解决问题。√运行者。他们在计算机系统上运行软件。√维护人员。他们维护、增强或变更软件。产品文档包括如下内容：√用于管理者的指南和资料，他们监督软件的使用。√宣传资料。通告软件产品的可用性并详细说明它的功能、运行环境等。√一般信息。对任何有兴趣的人描述软件产品。基本的产品文档有培训手册、参考手册和用户指南、软件支持手册、产品手册和信息广告。（4）管理文档管理文档建立在项目信息的基础上，诸如：√开发过程的每个阶段的进度和进度变更的记录。√软件变更情况的记录。√相对于开发的判定记录。√职责定义。这种文档从管理的角度规定涉及软件生存的信息。相关文档的详细规定和编写格式见GB8567-2006。（5）文档等级文档等级是指所所需文档的一个说明，它指出文档的范围、内容、格式及质量，可以根据项目、费用、预期用途、作用范围或其他因素选择文档等级。每个文档的质量必须在文档计划期间就有明确的规定，文档的质量可以按文档的形式和列出的要求划分为四级。√最低限度文档（1级文档）：适合开发工作量低于1人月的开发者自用程序。该文档应包含程序清单、开发记录、测试数据和程序简介。√内部文档（2级文档）：可用于在精心研究后被认为似乎没有与其他用户共享资源的专用程序。除1级文档提供的信息外，2级文档还包括程序清单内足够的注释以帮助用户安装和使用程序。√工作文档（3级文档）：适合于由同一单位内若干人联合开发的程序，或可被其他单位使用的程序。√正式文档（4级文档）：适合那些要正式发行供普遍使用的软件产品。关键性程序或具有重复管理应用性质（如工资计算）的程序需要4级文档。4级文档应遵守GB8567-2006的有关规定。（6）文档评审为了提高软件产品的质量，一个有效的方法就是在软件开发的每个阶段，对该阶段所形成的文档进行严格评审，这样可尽早发现问题，并及时采取措施予以解决，从而确保文档内容的正确性，避免或减少大的返工，同时为进入下一阶段的工作做好组织上和技术上的准备。无论项目大小或项目管理的正规化程度，需求评审和设计评审是必不可少的。需求评审进一步确认开发者和设计者已了解用户要求什么，及用户从开发者一方了解某些限制和约束。需求评审（可能需要一次以上）产生一个被认可的需求规格说明。基于对系统要做些什么的共同理解，才能着手详细设计。用户代表必须积极参与开发和需求评审，参与对需求文档的认可。设计评审通常安排两个主要的设计评审：概要设计评审和详细设计评审。在概要设计评审过程中，主要详细评审每个系统组成部分的基本设计方法和测试计划。系统规格说明应根据概要设计评审的结果加以修改。详细设计评审主要评审计算机程序和程序单元测试计划。设计评审产生的最终文档规定系统和程序将如何设计、开发和测试，以满足一致同意的需求。产品文档的计划应包括对下述内容的评审和认可：编排方式；技术准确度；复盖范围的完整性；对读者的适合程度；图表设计思想及最终图表（也应接受关于技术准确度、适合程度和完整性的单独评审）；在语法、标点及其他行文技巧方面的正确性；对格式和别的标准的遵守程度。评审一般采用评审会的方式进行，由软件开发单位负责人、用户代表、开发小组成员、科技管理人员和标准化人员等组成评审小组，必要时还可邀请外单位的希赛网参加。2.GB/T8567-2006GB8567-2006根据GB/T8566-2001的规定，主要对软件的开发过程和管理过程应编制的主要文档及其编制的内容、格式规定了基本要求。该标准原则上适用于所有类型的软件产品的开发过程和管理过程。（1）标准的内容GB8567-2006规定了文档过程，包括软件标准的类型（含产品标准和过程标准）、源材料的准备、文档计划、文档开发、评审、与其他公司的文档开发子合同；GB8567-2006规定了软件生存周期与各种文档的编制要求，包括可行性与计划研究、需求分析、设计、实现、测试、运行与维护共六个阶段的要求，以及在文档编制中应考虑的各种因素。GB8567-2006详细给出了25种文档编制的格式（但在文档的归类中，却只给出了其中的18种文档），包括可行性研究（研究）报告、软件开发计划、软件测试计划、软件安装计划、软件移交计划、运行概念说明、系统/子系统需求规格说明、接口需求规格说明、系统/子系统设计（结构设计）说明、接口设计说明、软件需求规格说明、数据需求说明、软件（结构）设计说明、数据库（顶层）设计说明、软件测试说明、软件测试报告、软件配置管理计划、软件质量保证计划、开发进度月报、项目开发总结报告、软件产品规格说明、软件版本说明、软件用户手册、计算机操作手册、计算机编程手册。GB8567-2006给出了这25种文件的具体内容，使用者可根据实际情况对该标准进行适当剪裁。GB8567-2006还规定了面向对象的软件应编制以下文档：总体说明文档、用例图文档、类图文档、顺序图文档、协作图（通信图）文档、状态图文档、活动图文档、构件图文档、部署图文档、包图文档。（2）文档的编制软件生命周期各阶段与软件文档编制工作的关系如表4-4所示。表4-4软件生命周期各阶段与软件文档编制工作的关系（3）文档的使用各类人员与软件文档的使用关系如表4-5所示。表4-5各类人员与软件文档的使用关系（4）文档的控制在软件的开发过程中，随着程序的逐步形成和逐步修改，各种文件也在不断地产生、不断地修改或补充。因此，必须加以周密的控制，以保持文件与程序产品的一致性，保持各种文件之间的一致性和文件的安全性。这种控制表现在以下六个方面：第一，就从事一项软件开发工作的开发集体而言，应设置一位专职的文件管理人员（接口管理工程师或文件管理员）；在开发集体中，应该集中保管本项目现有全部文件的主文本两套，由该文件管理人员负责保管。这两套主文本的内容必须完全一致。其中有一套是可供出借的，另一套是绝对不能出借的，以免发生万一；可出借的主文本在出借时必须办理出借手续，归还时办理注销出借手续。第二，每一份提交给文件管理人员的文件都必须具有编写人、审核人和批准人的签字。第三，开发集体中的工作人员可以根据工作的需要，在本项目的开发过程中持有一些文件，即所谓个人文件，包括为使他完成他承担的任务所需要的文件，以及他在完成任务过程中所编制的文件；但这种个人文件必须是主文本的复制品，必须同主文本完全一致，若要修改，必须首先修改主文本。第四，不同开发人员所拥有的个人文件通常是主文本的各种子集；所谓子集是指将主文本的各个部分根据承担不同任务的人员或部门的工作需要加以复制、组装而成的若干个文件的集合；文件管理人员应该列出一份不同子集的分发对象的清单，按照清单及时将文件分发给有关人员或部门。第五，一份文件如果已经被另一份新的文件所代替，则原文件应该被注销；文件管理人中要随时整理主文本，及时反映出文件的变化和增加情况，及时分发文件。第六，当一个项目的开发工作临近结束时，文件管理人员应逐个收回开发集体内每个成员的个人文件，并检查这些个人文件的内容；经验表明，这些个人文件往往可能比主文本更详细，或同主文本的内容有所不同，必须认真监督有关人员进行修改，使主文本能真正反映实际的开发结果。3.GB/T9385-2008GB/T9385-2008详细描述了SRS应该包含的内容及编写格式。该指南为软件需求实践提供了一个规范化的方法，不提倡将软件需求说明划分成等级，避免将它定义成更小的需求子集。该指南规定，SRS的内容应该包括以下四个方面：（1）前言：包括目的、范围、定义、简称和缩略语、引用文件、综述。（2）总体描述：包括产