GB T 16680 1996 软件文档管理指南1 L

 

中华人民共和国国家标准

软件文档管理指南 GB／T 16680--1996

                Guidelines  for the management of   neq  ISO/IEC TR 9294:1990

software documentation     

1   范围

 

    本标准为那些对软件或基于软件的产品的开发负有职责的管理者提供软件文档的管理指南．本标

准的目的在于协助管理者在他们的机构中产生有效的文档。

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

    本标准期望应用于各种类型的软件，从简单的程序到复杂的软件系统。并期望复盖各种类型的软件

文档，作用于软件生存期的各个阶段。

    不论项目的大小，软件文档管理的原则是一致的。对于小项目，可以不采用本标准中规定的有关细

节．管理者可剪裁这些内容以满足他们的特殊需要．

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

 

2  引用标准

 

   下列标准所包含的条文，通过在本标准中引用而构成为本标准的条文。本标准出版时，所示版本均

为有效，所有标准都会被修订，使用本标准的各方应探讨使用下列标准最新版本的可能性．

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

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

  GB/T 11457--].995  软件工程术语

 

3  定义

 

    本标准采用下列定义，其他定义见锄巾11457．

3.1  文档document

    一种数据媒体和其上所记录的数据．它具有永久性并可以由人或机器阅读．通常仅用于描述人工

可读的内容．例如，技术文件、设计文件、版本说明文件．

3.2  文档（集）I文档编制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  质量保证

    那些负责软件质量保证和评估系统性能的人员需要程序规格说明、测试和评估计划、测试该系统用

的各种质量标准，以及关于期望系统完成什么功能和系统怎样实现这些功能的清晰说明l必须制订测试

计划和测试规程，并报告测试结果J他们还必须说明和评估安全、控制、计算、检验例行程序及其他控制技术．这些文档的提供可满足质量保证人员和审查人员上述工作的需要．

4.4  培训与参考

    软件文档的另一个功能是使系统管理员、操作员、用户、管理者和其他有关人员了解系统如何工作，

以及为了达到他们的各自的目的，如何使用系统．

4.5  软件维护支持

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

求的变化或适应系统环境的变化．

4.6  历史档案

    软件文档可用作未来项目的一种资源．通常文档记载系统的开发历史，可使有关系统结构的基本思

想为以后的项目利用．系统开发人员通过审阅以前的系统以查明什么部分已试验过了，什么部分运行得

很好，什么部分因某种原因难以运行而被排除．良好的系统文档有助于把程序移植和转移到各种新的系

统环境中．

 

5  管理者的作用

 

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

 a)管理者对文档工作的责任．管理者要认识到正式或非正式文档都是重要的，还要认识到文档工

作必须包括文档计划、编写、修改、形成、分发和维护等各个方面．

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

    c)管理者的主要职责

    d)建立编制、登记、出版系统文档和软件文档的各种策略，

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

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

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

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

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

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

    一要求哪些类型的文档，

    一提供多少种文档，

    一文档包含的内容，

    一达到何种级别的质量水平，

    一何时产生何种文档，

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

    如果一个软件合同是有效的，应要求文档满足所接受的标准，并规定所提供的文档类型、每种文档

的质量水平以及评审和通过的规程．

 

6  制订文档编制策略

 

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

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

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

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

    在项目早期几个阶段就要求有文档，而且在贯穿软件开发过程中必须是可用的和可维护的．在开发

完成后，文档应满足软件的使用、维护、增强、转换或传输．

    b)文档应是可管理的

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

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

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

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

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

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

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

    f)应规定支持工具

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

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

 

7  制订文档编制标准和指南

 

在一个机构内部，应采用一些标准和指南；

——软件生存期模型，

    ——文档类型和相互关系，

    ——文档质量．

    这些标准和指南将决定如何实现文档任务，将提供一些准则以评价该机构内所产生的软件文档的

完整性、可用性和适合性．

    尽可能地采用现行的国家和国际标准，若现行的标准不适用，机构应制订自己的标准．

7.1   选择软件生存期模型

    现有的一些软件生存期模型，对于不同的阶段有不同词汇，从软件文档的观点来看，采用哪种模型

都无关紧要，只要阶段和相应的文档是清晰定义的、已计划的，并且对于任何具体软件项目是能遵循的．

因此，管理者应选择一个软件生存期模型并保证该模型在他们机构内是适用的．

    管理者将会发现所进行的阶段和相应任务的定义有助于监控软件项目的进展．相应于特定阶段生成的文档可用作该阶段的评审、通过和完成的检验点，而这种检验应在下一阶段开始前进行．

7.2  规定文档类型和内容

    下面给出软件文档主要类型的大纲，这个大纲不是详尽的或最后的，但适合作为主要类型软件文档

  的检验表．而管理者应规定何时定义他们的标准文档类型．

    软件文档归入如下三种类别l

    a)  开发文档——描述开发过程本身，

    b)产品文档——描述开发过程的产物，

    D管理文档——记录项目管理的信息．

7.2.1  开发文档

    开发文档是描述软件开发过程，包括软件需求、软件设计、软件测试、保证软件质量的一类文档，开发文档也包括软件的详细技术描述（程序逻辑、程序间相互关系、数据格式和存储等）．

    开发文档起到如下五种作用

    a）它们是软件开发过程中包含的所有阶段之间的通信工具，它们记录生成软件需求、设计、编码

  和测试的详细规定和说明’

    b)它们描述开发小组的职责．通过规定软件、主题事项、文档编制、质量保证人员以及包含在开

  发过程中任何其他事项的角色来定义做什么、如何做和何时做I

    c)它们用作检验点而允许管理者评定开发进度．如果开发文档丢失、不完整或过时，管理者将失

  去跟踪和控制软件项目的一个重要工具’

    d)  它们形成了维护人员所要求的基本的软件支持文档，而这些支持文档可作为产品文档的一部

  分

    e)它们记录软件开发的历史-

    基本的开发文档是，

    ——可行性研究和项目任务书

    ——需求规格说明

    ——功能规格说明，

    ——设计规格说明，包括程序和数据规格说明

    ——开发计划，

    ——软件集成和测试计划

    ——质量保证计划、标准、进度

    ——安全和测试信息。

 7.2.2  产品文档

产品文档规定关于软件产品的使用、维护、增强、转换和传输的信息．

    产品的文档起到如下三种作用．

    a)为使用和运行软件产品的任何人规定培训和参考信息，

    b)使得那些未参加开发本软件的程序员维护它

    c)促进软件产品的市场流通或提高可接受性．

    产品文档用于下列类型的读者，

    一用户他们利用软件输入数据、检索信息和解决问题

    一运行者他们在计算机系统上运行软件

    一维护人员他们维护、增强或变更软件。

    产品文档包括如下内容l

    一用于管理者的指南和资料，他们监督软件的使用，

    —宣传资料通告软件产品的可用性并详细说明它的功能、运行环境等，

    一般信息对任何有兴趣的人描述软件产品．

    基本的产品文档包括。

    一培训手册，

    一参考手册和用户指南

    一软件支持手册，

    一产品手册和信息广告．

7.2.3  管理文档

    这种文档建立在项目管理信息的基础上，诸如。

    一开发过程的每个阶段的进度和进度变更的记录，

    一软件变更情况的记录，

    —相对于开发的判定记录，

    一职责定义．

    这种文档从管理的角度规定涉及软件生存的信息．

    相关文档的详细规定和编写格式见GB 8667．

7.3  确定文档的质量等级

    仅仅依据规章、传统的做法或合同的要求去制作文档是不够的．管理者还必须确定文档的质量要求

以及如何达到和保证质量要求．

    质量要求的确定取决于可得到的资源、项目的大小和风险，可以对该产品的每个文档的格式及详细

程度作出明确的规定．

    每个文档的质量必须在文档计划期间就有明确的规定．文档的质量可以按文档的形式和列出的要．

求划分为四级．

    最底限度文档（1级文档）  1级文档适合开发工作量低于一个人月的开发者自用程序．该文档应包

含程序清单、开发记录、测试数据和程序简介．

    内部文档（2级文档）2级文档可用于在精心研究后被认为似乎没有与其他用户共享资源的专用程序．除1级文档提供的信息外，2级文档还包括程序清单内足够的注释以帮助用户安装和使用程序．

    工作文档（3级文档）3级文档适合于卣同一单位内若干人联合开发的程序，或可被其他单位使用

的程序．

    正式文档（4级文档）4级文档适合那些要正式发行供普遍使用的软件产品．关键性程序或具有重

复管理应用性质（如工资计算）的程序需要4级文档．4级文档应遵守OB 8667的有关规定．

    质量方面需要考虑的问题既要包含文档的结构，也要包含文档的内容。文档内容可以根据正确性、

完整性和明确性来判断．而文档结构由各个组成部分的顺序和总体安排的简单性来测定．要达到这四

个质量等级，需要的投入和资源逐级增加，质量保证机构必须处于适当的行政地位以保证达到期望的质

量等级

8 文档编制计划

文档计划可以是整个项目计划的一部分或是一个独立的文档。应该编写文档计划并把它分发给全

体开发组成员，作为文档重要性的具体依据和管理部门文档工作责任的备忘录．

    对于小的、非正式的项目，文档计划可能只有一页纸，对于较大的项目，文档计划可能是一个综合性的正式文档，这样的文档计划应遵循各项严格的标准及正规的评审和批准过程．

    编制计划的工作应及早开始，对计划的评审应贯穿项目的全过程．如同任何别的计划一样，文档计

划指出未来的各项活动，当需要修改时必须加以修改．导致对计划作适当修改的常规评审应作为该项目

工作的一部分，所有与该计划有关的人员都应得到文档计划．

    文档计划一般包括以下几方面内容

    a)列出应编制文档的目录，

    b)提示编制文档应参考的标准，

    c)指定文档管理员，

    d)提供编制文档所需要的条件，落实文档编写人员、所需经费以及编制工具等，

    e)明确保证文档质量的方法，为了确保文档内容的正确性、合理性，应采取一定的措施，如评审、鉴定等等，

    f)绘制进度表，以图表形式列出在软件生存期各阶段应产生的文档、编制人员、编制日期、完成日

期、评审日期等．

    附录B中的检查表为制定一个文档计划或评估现有文档计划的完整性提供帮助．

    此外，文档计划规定每个文档要达到的质量等级，以及为了达到期望的结果必须考虑哪些外部因

素．

文档计划还确定该计划和文档的分发，并且明确叙述参与文档工作的所有人员的职责．

 

9  制订文档规程

 

    文档编制规程应符合第6章概述的那些策略，并适用于整个软件产品生存期内的文档的编制和使

用．这些规程提出关于文档的计划、编制、评审、制作和分发的逻辑顺序．这些规程内含审批、质量保证及若干控制点，概述修改步骤、存储和维护要求以及更新方法。

    附录C中的检查表能帮助设计合适的规程或有助于评定现有规程的有效性．

9.1  文档计划制定

    项目一旦确定，就应制定项目开发计划（包括文档计划1），文档计划的制定遵照第8章的规定．

9.2  文档编写

    文档的编写是件非常细致的工作，从最初提出文档编写提纲开始，经过逐步充实、完善，并经反复检查和修改，直至正式交付使用为止．

  编写文档应注意以下几点   

    a)文档编写时间应与软件开发同步，在软件生存期的每一个阶段都应完成相应的文档编写工作，

  详见附录Dj

    b)按文档计划规定的文档数量和质量要求编写文档

    c）按OB 8567或本单位指定的标准内容和格式编写相应文档，

    d)文档用纸的格式由各单位按有关标准规定执行，

    e)每个文档必须装订成册，并加封面和目次，

    f)归档用的文档还应有扉页，用于各责任者的签署．

8.3  文档编号

   为便于管理，软件文档应按编号法进行编号．编号方法有十进分类法、隶属法等等，各单位可根据本单位实际情况确定一种编号方法．不论何种方法，编号应具有唯一性．

8.4  文档评审

    文档评审十分重要，文档评审必须与技术评审结合起来．

    为了提高软件产品的质量，一个有效的方法就是在软件开发的每个阶段，对该阶段所形成的文档进

行严格评审，这样可尽早发现问题，并及时采取措施予以解决，从而确保文档内容的正确性，避免或减，

少大的返工，同时为进入下一阶段的工作做好组织上和技术上的准备．

    对一些大项目，正规评审通常在开发方法学指导下进行．正规评审应包括文档评审，这是为了保证

文档不但正确，而且内容是最新的．如果对文档与开发工作的其他方面同样重要这一点强调不够，各种

问题可能随之而来。

    对所有描述开发工作和产品的文档进行评审是正规评审过程的组成部分．一开始特别重要的是需

一求规格说明和设计规格说明的评审．

    需求评审需求评审进一步确认开发者和设计者已了解用户要求什么，及用户从开发者一方了解

某些限制和约束．

    需求评审（可能需要一次以上）产生一个被认可的需求规格说明．基于对系统要做些什么的共同理

解，才能着手详细设计．用户代表必须积极参与开发和需求评审，参与对需求文档的认可．

    设计评审通常安排两个主要的设计评审l概要设计评审和详细设计评审．

    在概要设计评审过程中，主要详细评审每个系统组成部分的基本设计方法和测试计划．系统规格说 明应根据概要设计评审的结果加以修改．

    详细设计评审主要评审计算机程序和程序单元测试计划．

    设计评审产生的最终文档规定系统和程序将如何设计、开发和测试，以满足一致同意的需求．正规

备忘录提供一份有关所有会议的记录．

    无论项目大小或项目管理的正规化程度，需求评审和设计评审是必不可少的．需求必须说明清楚，

用户和开发者双方都必须理解需求，为了能把需求转换成程序及程序成分，设计的细节须经同意并写成

文档。

    其他评审其他文档的正规评审也是必需的．产品文档的计划应包括对下述内容的评审和认可

    a)编排方式，

    b)技术准确度

    c)复盖范围的完整性，

    d)对读者的适合程度，

    e)图表设计思想及最终图表（也应接受关于技术准确度、适合程度和完整性的单独评审），

    f)在语法、标点及其他行文技巧方面的正确性，

    g)对格式和别的标准的遵守程度．

    如果有标准和指南（现有的或制定的），则可以对照这些标准来评判文档．正规评审要保证产品文档

是准确的、完整的，而且是适合读者的，   

    附录E提供了软件开发过程各评审点评审内容．

    评审一般采用评审会的方式进行，其步骤为一

    a) 由软件开发单位负责人、用户代表、开发小组成员、科技管理人员和标准化人员等组成评审小

组，必要时还可邀请外单位的专家参加l

    b)开会前，由开发单位负责人确定评审的具体内容，并将评审材料发给评审小组成员，要求做好评审准备，

    c)  由开发单位负责人主持评审会，根据文档编制者对该文档的说明和评审条目，由评审小组成员

进行评议、评审，评审结束应作出评审结论，评审小组成员应在评审结论上签字．

9.5  文档签署

    软件产品的所有文档，都应按规定进行签署．

    软件文档签署的顺序一般按编写÷审核÷会签啼标准化啼批准的顺序进行。其中会签仅在必要时

才进行．

    签署不允许代签．

    修改单的签署与被修改的文档签署相同．

    附录F提了供软件文档签署者．

284