软件文档管理指南

鼯鼠

1 范围

    本标准为那些对软件或基于软件的产品的开发负有职责的管理者提供软件文档的管理指南。本标准的目的在于协助管理者在他们的机构中产生有效的文档。

    本标准涉及策略、标准、规程、资源和计划，管理者必须关注这些内容，以便有效地管理软件文档。

    本标准期望应用于各种类型的软件，从简单的程序到复杂的软件系统。并期望覆盖各种类型的软件文档，作用于软件生存期的各个阶段。

    不论项目的大小，软件文档管理的原则是一致的。对于小项目，可以不采用本标准中规定的有关细节。管理者可剪裁这些内容以满足他们的特殊需要。

    本标准是针对文档编制管理而提出的，不涉及软件文档的内容和编排。

    2 引用标准

    下列标准所包含的条文，通过在本标准中引用而构成为本标准的条文。本标准出版时，所示版本均为有效，所有标准都会被修订，使用本标准的各方应探讨使用下列标准最新版本的可能性。

    GB 8566-88 计算机软件开发规范

    GB 8567-88 计算机软件产品开发文件编制指南

    GB/T 11457-1995 软件工程术语

    3 定义

    本标准采用下列定义，其他定义见 GB/T 11457 。

    3.1 文档 document

    一种数据媒体和其上所记录的数据。它具有永久性并可以由人或机器阅读。通常仅用于描述人工可读的内容。例如，技术文件、设计文件、版本说明文件。

    3.2 文档（集）；文档编制 documentation

    一个或多个相关文档的集合。

    3.3 文档计划 documentation plan

    一个描述文档编制工作方法的管理用文档。该计划主要描述要编制什么类型的文档，这些文档的内容是什么，何时编写，由谁编写，如何编写，以及什么是影响期望结果的可用资源和外界因素。

    3.4 文档等级 level of documentation

    对所需文档的一个说明，它指出文档的范围、内容、格式及质量，可以根据项目、费用、预期用途、作用范围或其他因素选择文档等级。

    3.5 软件产品 software product

    软件开发过程的结果，并推出供用户使用的软件实体。

    4 软件文档的作用

    a) 管理依据；

    b) 任务之间联系的凭证；

    c) 质量保证；

    d) 培训与参考；

    e) 软件维护支持；

    f) 历史档案。

    4.1 管理依据

    在软件开过过程中，管理者必须了解开发进度、存在的问题和预期目标。每一阶段计划安排的定期报告提供了项目的可见性。定期报告还提醒各级管理者注意该部门对项目承担的责任以及该部门效率的重要性。开发文档规定若干个检查点和进度表，使管理者可以评定项目的进度，如果开发文档有遗漏，不完善，或内容陈旧，则管理者将失去跟踪和控制项目的重要依据。

    4.2 任务之间联系的凭证

    大多数软件开发项目通常被划分成若干个任务，并由不同的小组去完成。学科方面的专家建立项目，分析员阐述系统需求，设计员为程序员制定总体设计，程序员编制详细的程序代码，质量保证专家和审查员评价整个系统性能和功能的完整性，负责维护的程序员改进各种操作或增强某些功能。

    这些人员需要的互相联系是通过文档资料的复制、分发和引用而实现的，因而，任务之间的联系是文档的一个重要功能。大多数系统开发方法为任务的联系规定了一些正式文档。分析员向设计员提供正式需求规格说明，设计员向程序员提供正式设计规格说明，等等。

  

鼯鼠

  4.3 质量保证

    那些负责软件质量保证和评估系统性能的人员需要程序规格说明、测试和评估计划、测试该系统用的各种质量标准以及关于期望系统完成什么功能和系统怎样实现这些功能的清晰说明；必须制订测试计划和测试规程，并报告测试结果；他们还必须说明和评估完全、控制、计算、检验例行程序及其他控制技术。这些文档的提供可满足质量保证人员和审查人员上述工作的需要。

    4.4 培训与参考

    软件文档的另一个功能是使系统管理员、操作员、用户、管理者和其他有关人员了解系统如何工作，以及为了达到他们的各自的目的，如何使用系统。

    4.5 软件维护支持

    维护人员需要软件系统的详细说明以帮助他们熟悉系统，找出并修正错误，改进系统以适应用户需求的变化或适应系统环境的变化。

    4.6 历史档案

    软件文档可用作未来项目的一种资源。通常文档记载系统的开发历史，可使有关系统结构的基本思想为以后的项目利用。系统开发人员通过审阅以前的系统以查明什么部分已试验过了，什么部分运行得很好，什么部分因某种原因难以运行而被排除。良好的系统文档有助于把程序移植和转移到各种新的系统环境中。

    5 管理者的作用

    管理者严格要求软件开发人员和编制组完成文档编制，并且在策略、标准、规程、资源分配和编制计划方面给予支持。

    a) 管理者对文档工作的责任。管理者要认识到正式或非正式文档都是重要的，还要认识到文档工作必须包括文档计划、编写、修改、形成、分发和维护等各个方面。

    b) 管理者对文档工作的支持。管理者应为编写文档的人员提供指导和实际鼓励，并使各种资源有效地用于文档开发。

    c) 管理者的主要职责：

    1 ） 建立编制、登记、出版系统文档和软件文档的各种策略；

    2 ） 把文档计划作为整个开发工作的一个组成部分；

    3 ） 建立确定文档质量、测试质量和评审质量的各种方法的规程；

    4 ） 为文档的各个方面 确定和准备各种标准和指南；

    5 ） 积极支持文档工作以形成在开发工作中自觉编制文档的团队风气；

    6 ） 不断检查已建立起来的过程，以保证符合策略和各种规程并遵守有关标准和指南。

    通常，项目管理者在项目开发前应决定如下事项：

    要求哪些类型的文档；

    提供多少种文档；

    文档包含的内容；

    达到何种级别的质量水平；

    何时产生何种文档；

    如何保存、维护文档以及如何进行通信。

    如果一个软件合同是有效的，应要求文档满足所接受的标准，并规定所提供的文档类型、每种文档的质量水平以及评审和通过的规程。

    6 制订文档编制策略

    文档策略是由上级（资深）管理者新任务并支持的，对下级开发单位或开发人员提供指导。策略规定主要的方向不是做什么或如何做的详细说明。

    一般说来，文档编制策略陈述要明确，并通告到每个人且理解它，进而使策略被他们贯彻实施。

    支持有效文档策略的基本条件：

    a) 文档需要覆盖整个软件生存期

    在项目早期几个阶段就要求有文档，而且在贯穿软件开发过程中必须是可用的和可维护的。在开发完成后，文档应满足软件的使用、维护、增强、转换或传输。

    b) 文档应是可管理的

    指导和控制文档的获得维护，管理者和发行专家应准备文档产品、进度、可靠性、资源，质量保证和评审规程的详细计划大纲。

    c) 文档应适合于它的读者

    读者可能是管理者、分析员、无计算机经验的专业人员、维护人员、文书人员等。根据任务的执行，他们要求不同的材料表示和不同的详细程度。针对不同的读者，发行专家应负责设计不同类型的文档。

    d) 文档效应应贯穿到软件的整个开发过程中

    在软件开发的整个过程中，应充分体现文档的作用和限制，即文档应指导全部开发过程。

    e) 文档标准应被标识和使用

    应尽可能地采纳现行的标准，若没有合适的现行标准，必要时应研制适用的标准或指南。

    f) 应规定支持工具

    工具有助于开发和维护软件产品，包括文档。因此尽可能地使用工具是经济的、可行的。

    附录 A 中的检查表为制定策略条款或评估现有策略条款的有效性和完整性提供帮助。