软件文档管理指南.docx
《软件文档管理指南.docx》由会员分享，可在线阅读，更多相关《软件文档管理指南.docx（75页珍藏版）》请在冰豆网上搜索。
软件文档管理指南
软件文档管理指南
计算机软件文档管理指南
一、范围
本标准为那些对软件或基于软件的产品的开发负有职责的管理者提供软件文档的管理指南。
本标准的目的在于协助管理者在他们的机构中产生有效的文档。
本标准涉及策略、标准、规程、资源和计划，管理者必须关注这些内容，以便有效地管理软件文档。
本标准期望应用于各种类型的软件，从简单的程序到复杂的软件系统。
并期望覆盖各种类型的软件文档，作用于软件生存期的各个阶段。
不论项目的大小，软件文档管理的原则是一致的。
对于小项目，可以不采用本标准中规定的有关细节。
管理者可剪裁这些内容以满足他们的特殊需要。
本标准是针对文档编制管理而提出的，不涉及软件文档的内容和编排。
二、引用标准
下列标准所包含的条文，通过在本标准中引用而构成为本标准的条文。
本标准出版时，所示版本均为有效，所有标准都会被修订，使用本标准的各方应探讨使用下列标准最新版本的可能性。
GB8566-88计算机软件开发规范
GB8567-88计算机软件产品开发文件编制指南
GB/T11457-1995软件工程术语
三、定义
本标准采用下列定义，其他定义见GB/T11457。
1、文档document
一种数据媒体和其上所记录的数据。
它具有永久性并可以由人或机器阅读。
通常仅用于描述人工可读的内容。
例如，技术文件、设计文件、版本说明文件。
2、文档（集）；文档编制documentation
一个或多个相关文档的集合。
3、文档计划documentationplan
一个描述文档编制工作方法的管理用文档。
该计划主要描述要编制什么类型的文档，这些文档的内容是什么，何时编写，由谁编写，如何编写，以及什么是影响期望结果的可用资源和外界因素。
4、文档等级levelofdocumentation
对所需文档的一个说明，它指出文档的范围、内容、格式及质量，可以根据项目、费用、预期用途、作用范围或其他因素选择文档等级。
5、软件产品softwareproduct
软件开发过程的结果，并推出供用户使用的软件实体。
四、软件文档的作用
（一）管理依据；
（二）任务之间联系的凭证；
（三）质量保证；
（四）培训与参考；
（五）软件维护支持；
（六）历史档案。
（一）管理依据
在软件开过过程中，管理者必须了解开发进度、存在的问题和预期目标。
每一阶段计划安排的定期报告提供了项目的可见性。
定期报告还提醒各级管理者注意该部门对项目承担的责任以及该部门效率的重要性。
开发文档规定若干个检查点和进度表，使管理者可以评定项目的进度，如果开发文档有遗漏，不完善，或内容陈旧，则管理者将失去跟踪和控制项目的重要依据。
（二）任务之间联系的凭证
大多数软件开发项目通常被划分成若干个任务，并由不同的小组去完成。
学科方面的专家建立项目，分析员阐述系统需求，设计员为程序员制定总体设计，程序员编制详细的程序代码，质量保证专家和审查员评价整个系统性能和功能的完整性，负责维护的程序员改进各种操作或增强某些功能。
这些人员需要的互相联系是通过文档资料的复制、分发和引用而实现的，因而，任务之间的联系是文档的一个重要功能。
大多数系统开发方法为任务的联系规定了一些正式文档。
分析员向设计员提供正式需求规格说明，设计员向程序员提供正式设计规格说明，等等。
（三）质量保证
那些负责软件质量保证和评估系统性能的人员需要程序规格说明、测试和评估计划、测试该系统用的各种质量标准以及关于期望系统完成什么功能和系统怎样实现这些功能的清晰说明；必须制订测试计划和测试规程，并报告测试结果；他们还必须说明和评估完全、控制、计算、检验例行程序及其他控制技术。
这些文档的提供可满足质量保证人员和审查人员上述工作的需要。
（四）培训与参考
软件文档的另一个功能是使系统管理员、操作员、用户、管理者和其他有关人员了解系统如何工作，以及为了达到他们的各自的目的，如何使用系统。
（五）软件维护支持
维护人员需要软件系统的详细说明以帮助他们熟悉系统，找出并修正错误，改进系统以适应用户需求的变化或适应系统环境的变化。
（六）历史档案
软件文档可用作未来项目的一种资源。
通常文档记载系统的开发历史，可使有关系统结构的基本思想为以后的项目利用。
系统开发人员通过审阅以前的系统以查明什么部分已试验过了，什么部分运行得很好，什么部分因某种原因难以运行而被排除。
良好的系统文档有助于把程序移植和转移到各种新的系统环境中。
五、管理者的作用
管理者严格要求软件开发人员和编制组完成文档编制，并且在策略、标准、规程、资源分配和编制计划方面给予支持。
（一）管理者对文档工作的责任。
管理者要认识到正式或非正式文档都是重要的，还要认识到文档工作必须包括文档计划、编写、修改、形成、分发和维护等各个方面。
（二）管理者对文档工作的支持。
管理者应为编写文档的人员提供指导和实际鼓励，并使各种资源有效地用于文档开发。
（三）管理者的主要职责：
1、建立编制、登记、出版系统文档和软件文档的各种策略；
2、把文档计划作为整个开发工作的一个组成部分；
3、建立确定文档质量、测试质量和评审质量的各种方法的规程；
4、为文档的各个方面确定和准备各种标准和指南；
5、积极支持文档工作以形成在开发工作中自觉编制文档的团队风气；
6、不断检查已建立起来的过程，以保证符合策略和各种规程并遵守有关标准和指南。
通常，项目管理者在项目开发前应决定如下事项：
要求哪些类型的文档；
提供多少种文档；
文档包含的内容；
达到何种级别的质量水平；
何时产生何种文档；
如何保存、维护文档以及如何进行通信。
如果一个软件合同是有效的，应要求文档满足所接受的标准，并规定所提供的文档类型、每种文档的质量水平以及评审和通过的规程。
六、制订文档编制策略
文档策略是由上级（资深）管理者新任务并支持的，对下级开发单位或开发人员提供指导。
策略规定主要的方向不是做什么或如何做的详细说明。
一般说来，文档编制策略陈述要明确，并通告到每个人且理解它，进而使策略被他们贯彻实施。
支持有效文档策略的基本条件：
（一）文档需要覆盖整个软件生存期
在项目早期几个阶段就要求有文档，而且在贯穿软件开发过程中必须是可用的和可维护的。
在开发完成后，文档应满足软件的使用、维护、增强、转换或传输。
（二）文档应是可管理的
指导和控制文档的获得维护，管理者和发行专家应准备文档产品、进度、可靠性、资源，质量保证和评审规程的详细计划大纲。
（三）文档应适合于它的读者
读者可能是管理者、分析员、无计算机经验的专业人员、维护人员、文书人员等。
根据任务的执行，他们要求不同的材料表示和不同的详细程度。
针对不同的读者，发行专家应负责设计不同类型的文档。
（四）文档效应应贯穿到软件的整个开发过程中
在软件开发的整个过程中，应充分体现文档的作用和限制，即文档应指导全部开发过程。
（五）文档标准应被标识和使用
应尽可能地采纳现行的标准，若没有合适的现行标准，必要时应研制适用的标准或指南。
（六）应规定支持工具
工具有助于开发和维护软件产品，包括文档。
因此尽可能地使用工具是经济的、可行的。
附录A中的检查表为制定策略条款或评估现有策略条款的有效性和完整性提供帮助。
七、制订文档编制标准和指南
在一个机构内部，应采用一些标准和指南：
（一）软件生存期模型；
（二）文档类型和相互关系；
（三）文档质量。
这些标准和指南决定如何实现文档任务，将提供一些准则以评价机构内所产生的软件文档的完整性、可用性和适合性。
尽可能地采用现行的国家和国际标准，若现行的标准不适用，机构应制订自己的标准。
1、选择软件生存期模型
现有的一些软件生存期模型，对于不同的阶段有不同的词汇，从软件文档的观点来看，采用哪种模型都无关紧要，只要阶段和相应的文档是清晰定义的、已计划的，并且对于任何具体软件项目是能遵循的。
因此，管理者应选择一个软件生存期模型并保证该模型在他们机构内是适用的。
管理者将会发现所进行的阶段和相应任务的定义有助于监控软件项目的进展。
相应于特定阶段生成的文档可用作该阶段的评审、通过和完成的检验点，而这种检验应在下一阶段开始前进行。
2、规定文档类型和内容
下面给出软件文档主要类型的大纲，这个大纲不是详尽的或最后的，但适合作为主要类型软件文档的检验表。
而管理者应规定何时定义他们的标准文档类型。
软件文档归入如下三种类别：
1）开发文档——描述开发过程本身；
2）产品文档——描述开发过程的产物；
3）管理文档——记录项目管理的信息。
1）开发文档
开发文档是描述软件开发过程，包括软件需求、软件设计、软件测试、保证软件质量的一类文档，开发文档也包括软件的详细技术描述（程序逻辑、程序间相互关系、数据格式和存储等）。
开发文档起到如下五种作用：
a）它们是软件开发过程中包含的所有阶段之间的通信工具，它们记录生成软件需求、设计、编码和测试的详细规定和说明；
b）它们描述开发小组的职责。
通过规定软件、主题事项、文档编制、质量保证人员以及包含在开发过程中任何其他事项的角色来定义做直截了当、如何做和何时做；
c）它们用作检验点而允许管理者评定开发进度。
如果开发文档丢失、不完整或过时，管理者将失去跟踪和控制软件项目的一个重要工具；
d）它们形成了维护人员所要求的基本的软件支持文档。
而这些支持文档可作为产品文档的一部分；
e）它们记录软件开发的历史。
基本的开发文档是：
——可行性研究和项目任务书；
——需求规格说明；
——功能规格说明；
——设计规格说明，包括程序和数据规格说明；
——开发计划；
——软件集成和测试计划；
——质量保证计划、标准、进度；
安全和测试信息。
2）产品文档
产品文档规定关于软件产品的使用、维护、增强、转换和传输的信息。
产品的文档起到如下三种作用：
a）为使用和运行软件产品的任何人规定培训和参考信息；
b）使得那些未参加开发本软件的程序员维护它；
c）促进软件产品的市场流通或提高可接受性。
产品文档用于下列类型的读者：
用户——他们利用软件输入数据、检索信息和解决问题；
运行者——他们在计算机系统上运行软件；
维护人员——他们维护、增强或变更软件。
产品文档包括如下内容：
用于管理者的指南和资料，他们监督软件的使用；
宣传资料通告软件产品的可用性并详细说明它的功能、运行环境等；
一般信息对任何有兴趣的人描述软件产品。
基本的产品文档包括：
培训手册；
参考手册和用户指南；
软件支持手册；
产品手册和信息广告。
3）管理文档
这种文档建立在项目管理信息的基础上，诸如：
开发过程的每个阶段的进度和进度变更的记录；
软件变更情况的记录；
相对于开发的判定记录；
职责定义。
这种文档从管理的角度规定涉及软件生存的信息。
相关文档的详细规定和编写格式见GB8567。
3、确定文档的质量等级
仅仅依据规章、传统的做法或合同的要求去制作文档是不够的。
管理者还必须确定文档的质量要求以及如何达到和保证质量要求。
质量要求的确定取决于可得到的资源、项目的大小和风险，可以对该产品的每个文档的格式及详细程度作出明确的规定。
每个文档的质量必须在文档计划期间就有明确的规定。
文档的质量可以按文档的形式和列出的要坟划分为四级。
最低限度文档（1级文档）1级文档适合开发工作量低于一个人月的开发者自用程序。
该文档应包含程序清单、开发记录、测试数据和程序简介。
内部文档（2级文档）2级文档可用于在精心研究后被认为似乎没有与其他用户共享资源的专用程序。
除1级文档提供的信息外，2级文档还包括程序清单内足够的注释以帮助用户安装和使用程序。
工作文档（3级文档）3级文档适合于由同一单位内若干人联合开发的程序，或可被其他单位使用的程序。
正式文档（4级文档）4级文档适合那些要正式发行供普遍使用的软件产品。
关键性程序或具有重复管理应用性质（如工资计算）的程序需要4级文档。
4级文档遵守GB8567的有关规定。
质量方面需要考虑的问题即要包含文档的结构，也要包含文档的内容。
文档内容可以根据正确性、完整性和明确性来判断。
而文档结构由各个组成部分的顺序和总体安排的简单性来测定。
要达到这四个质量等级，需要的投入和资源逐级增加，质量保证机构必须处于适当的行政地位以保证达到期望的质量等级。
八、文档编制计划
文档计划可以是整个项目计划的一部分或是一个独立的文档。
应该编写文档计划并把它分发给全体开发组成员，作为文档重要性的具体依据和管理部门文档工作责任的备忘录。
对于小的、非正式的项目，文档计划可能只有一页纸；对于较大的项目，文档计划可能是一个综合性的正式文档，这样的文档计划应遵循各项严格的标准及正规的评审和批准过程。
编制计划的工作应及早开始，对计划的评审应贯穿项目的全过程。
如同任何别的计划一样，文档计划指出未来的各项活动，当需要修改时必须加以修改。
导致对计划作适当修改的常规评审应作为该项目工作的一部分，所有与该计划有关的人员都应得到文档计划。
文档计划一般包括以下几方面内容：
1）列出应编制文档的目录；
2）提示编制文档应参考的标准；
3）指定文档管理员；
4）提供编制文档所需要的条件，落实文档编写人员、所需经费以及编制工具等；
5）明确保证文档质量的方法，为了确保文档内容的正确性、合理性，应采取一定的措施，如评审、鉴定等等；
6）绘制进度表，以图表形式列出在软件生存期各阶段应产生的文档、编制人员、编制日期、完成日期、评审日期等。
附录B中的检查表为制定一个文档计划或评估现有文档计划的完整性提供帮助。
此外，文档计划规定每个文档要达到的质量等级，以及为了达到期望的结果必须考虑哪些外部因素。
文档计划还确定该计划和文档的分发，并且明确叙述与文档工作的所有人员的职责。
计算机软件需求说明编制指南
一、引言
（一）目的和作用
本指南为软件需求实践提供了一个规范化的方法。
本指南不提倡把软件需求说明（SoftwareRequirementsSpecifications，以下简称SRS）划分成等级，避免把它定义成更小的需求子集。
本指南适用对象：
软件客户（Customers），以便精确地描述他们想获得什么样的产品。
软件开发者（Suppliers），以便准确地理解客户需要什么样的产品。
对于任一要实现下列目标的单位和（或）个人：
1.要提出开发规范化的SRS提纲；
2.定义自己需要的具体的格式和内容；
3.产生附加的局部使用条款，如SRS质量检查清单或者SRS作者手册等。
SRS将完成下列目标：
1.在软件产品完成目标方面为客户和开发者之间建立共同协议创立一个基础。
对要实现的软件功能做全面描述，帮助客户判断所规定的软件是否符合他们的要求，或者怎样修改这种软件才能适合他们的要求；
2.提高开发效率。
编制SRS的过程将使客户在设计开始之前周密地思考全部需求，从而减少事后重新设计、重新编码和重新测试的返工活动。
在SRS中对各种需求仔细地进行复查，还可以在开发早期发现若干遗漏、错误的理解和不一致性，以便及时加以纠正；
3.为成本计价和编制计划进度提供基础。
SRS提供的对被开发软件产品的描述，是计算机软件产品成本核算的基础，并且可以为各方的要价和付费提供依据。
SRS对软件的清晰描述，有助于估计所必须的资源，并用作编制进度的依据；
4.为确认和验证提供一个基准。
任何组织将更有效地编制他们的确认和验证计划。
作为开发合同的一部分，SRS还可以提供一个可以度量和遵循的基准（然而，反之则不成立，即任一有关软件的合同都不能作为SRS。
因为这种文件几乎不包括详尽的需求说明，并且通常不完全的）；
5.便于移植。
有了SRS就便于移值软件产品，以适应新的用户或新的机种。
客户也易于移植其软件到其他部门，而开发者同样也易于把软件移植到新的客户；
6.作为不断提高的基础。
由于SRS所讨论的是软件产品，而不是开发这个产品的设计。
因此SRS是软件产品继续提高的基础。
虽然SRS也可能要改变，但是原来的SRS还是软件产品改进的可靠基础。
（二）范围
本指南适用于编写软件需求规格说明，它描述了一个SRS所必须的内容和质量，并且在第6章中提供了SRS大纲。
1、引用标准
GB8566计算机软件开发规范
GB8567计算机软件产品开发文件编制指南
GB/T11457软件工程术语
2、定义
GB/T11457所列术语和下列定义适用于本指南。
合同（contract是由客户和开发者共同签署的具有法律约束力的文件。
其中包括产品的技术、组织、成本和进度计划要求等内容。
客户（customer）指个人或单位，他们为产品开发提供资金，通常（但有时也不必）还提出各种需求。
文件中的客户和开发者也可能是同一个组织的成员。
语言（language）是具有语法和语义的通信工具，包括一组表达式、惯例和传递信息的有关规则。
分割（partitioning）把一个整体分成若干部分。
开发者（supplier）指为客户生产某种软件产品的个人或集团。
在本指南中，客户和开发者可能是同一个组织的成员。
用户（user）指运行系统或者直接与系统发生交互作用的个人或集团。
用户和客户通常不是同一些人。
3、编写SRS的背景信息
（1）SRS的基本要求
SRS是对要完成一定功能、性能的软件产品、程序或一组程序的说明。
对SRS的描述有两项基本要求：
1、必须描述一定的功能、性能；
2、必须用确定的方法叙述这些功能、性能。
（2）SRS的环境
必须认识到SRS在整个软件开发规范（见GB8566）所规定的有关阶段都起作用。
正因为如此，SRS的起草者必须特别注意不要超出这种作用的范围。
这意味着要满足下列要求：
1.SRS必须正确地定义所有的软件需求；
2.除了设计上的特殊限制之外，SRS中一般不描述任何设计、验证或项目管理细节。
（3）SRS的特点
1）、无歧义性
当且仅当它对每一个需求只有一种解释时，SRS者是无歧义的。
1.要求最终产品的每一个特性用某一术语描述；
2.若某一术语在某一特殊的行文中使用时具有多种歧义，那么对该术语的每种含义作出解释并指出其适用场合。
需求通常是用自然语言编写的，使用自然语言的SRS起草者必须特别注意消除其需求的歧义性。
提倡使用形式化需求说明语言。
（4）完整性
如果一个SRS能满足下列要求，则该SRS就是完整的：
1.包括全部有意义的要求，无论是关系到功能的、性能的、设计约束的，还是关系到属性或外部接口方面的需求；
2.对所有可能出现的输入数据的响应予以定义，要对合法和非合法的输入值的响应做出规定；
3.要符合SRS要求。
如果个别章节不适用，则在SRS中要保留章节号；
4.填写SRS中的全部插图、表、图示标记和参照，并且定义全部术语和度量单位。
（5）关于使用“待定”一词的规定
任何一个使用“待定”的SRS都是不完全的。
1.若万一遇到使用“待定”一词时，作如下处理：
（1）对产生“待定”一词的条件进行描述，使得问题能被解决；
（2）描述必须干什么事，以删除这个“待定”；
2.包含有“待定”一词的任何SRS的项目文件应该：
（1）标识与此特定文件有关的版本号或叙述其专门的发布号；
（2）拒绝任何仍标识为“待定”一词的SRS章节的许诺。
3、可验证性
当且仅当SRS中描述的每一个需求都是可以验证的，该SRS才是可以验证的；当且仅当在某一性能价格比可取的有限处理过程，人或机器能通过该过程检查软件产品能否满足需求时，才称这个需求是可以验证的。
4、一致性
当且仅当SRS中各个需求的描述是不矛盾时SRS才是一致的。
5、可修改性
如果一个SRS的结构和风格在需求有必要改变时是易于实现的、完整性的、一致的，那么这个SRS就是可以修改的。
可修改性要求SRS具备以下条件：
（1）、具有一个有条不紊的易于使用的内容组织，具有目录表，索引和明确的交叉引用表；
（2）.没有冗余。
即同一需求不能在SRS中出现多次。
（3）冗余本身不是错误，但是容易发生错误。
冗余可增加SRS的可读性，但是在一个冗余文件被更新时容易出现问题。
例如：
假设一个明确的需求在两个地方详细列出，后来发现这个需求需要改变，若只修改一个地方，于是SRS就变得不一致了。
（4）不管冗余是否必须，SRS一定要包含一个详细的交叉引用表，以便SRS具备可修改性。
6、可追踪性
如果每一个需求的源流是清晰的，在进一步产生和改变文件编制时，可以方便地引证每一个需求，则该SRS就是可追踪的。
建议采用如下两种类型的追踪：
（1）向后追踪（即向已开发过的前一阶段追踪）。
根据先前文件或本文件前面的每一个需求进行追踪。
（2）向前追踪（即是向由SRS派生的所有文件追踪）。
根据SRS中具有唯一的名字和参照号的每一个需求进行追踪。
当SRS中的一个需求表达另一个需求的一种指派或者是派生的，向前、向后的追踪都要提供。
例如：
（3）从总的用户响应时间需求中分配给数据库操作响应时间；
（4）识别带有一定功能和用户接口的需求的报告格式；
（5）支持法律或行政上需要的某个软件产品（例如，计算税收）。
在这种情况下，要指出软件所支持的确切的法律或行政文件。
当软件产品进入运行和维护阶段时，SRS的向前可追踪性显得特别重要。
当编码和设计文件作修改时，重要的是要查清这些修改所影响的全部需求。
7、运行和维护阶段的可使用性
SRS必须满足运行和维护阶段的需要，包括软件最终替换。
1.维护常常是由与原来开发无联系的人来进行的。
局部的改变（修正）可以借助于好的代码注释来实现。
对于较大范围的改变。
设计和需求文件是必不可少的，这里隐含了两个作用：
（1）如4.3.5条指出，SRS必须是可修改的；
（2）SRS中必须包括一个记录，它记录那些应用于各个成分的所有具体条文。
例如：
它们的危急性（如故障可能危及完全或导致大量财政方面和社会方面的损失）；
它们仅与暂时的需要相关（如支持一种可立即恢复原状的显示）；
它们的来源（如某功能是由已存在的软件产品的全部拷贝复制而成）。
2.要求在SRS中清楚地写明功能的来源和目的，因为对功能的来源和引入该功能的目的不清楚的话，通常不可能很好地完成软件的维护。
8、SRS的编制者
软件开发的过程是由开发者和客户双方同意开发什么样的软件协议开始的。
这种协议要使用SRS的形式，应该由双方联合起草。
这是因为：
（1）客户通常对软件设计和开发过程了解较少，而不能写出可用的SRS；
（2）开发者通常对于客户的问题和意图了解较少，从而不可能写出一个令人满意的系统需求。
9、SRS的改进
软件产品的开发过程中，在项目的开始阶段不可能详细说明某些细节，在开发过程中可能发现SRS的缺陷、缺点和错误之类的问题，所以可能要对SRS进行改进。
在SRS的改进中，应注意如下事项：
10、尽管可以预见校正版本的开发以后不可避免，而对需求还必须尽可能完全、清楚地描述。
11、一旦最初识别出项目的
升级会员 