GBT 16680-1996 软件文档管理指南.pdf

中华人民共和国国家标准软 件 文 档 管 理 指 南发布实施国 家 技 术 监 督 局发 布前言本标准非等效采用国际标准信息技术软件文档管理指南本标准与的主要差别如下个别章条作了调整所引用的标准作了变更定义部分增加了内容技术要素充实了内容 增加了一些实用措施如 文档编写 签署 审查 归档和修改等内容附录部分也作了调整和扩充 主要是增加了附录附录和附录本标准的附录到附录均是提示的附录本标准由中华人民共和国电子工业部提出本标准由电子工业部标准化研究所归口本标准起草单位 电子工业部标准化研究所 华东计算技术研究所本标准主要起草人 冯惠 王家增 郑人杰前言国际标准化组织 和国际电工委员会 是世界性的标准化专门机构国家成员体 它们都是或的成员国 通过国际组织建立的各个技术委员会参与制定针对特定技术范围的国际标准和的各技术委员会在共同感兴趣的领域内进行合作与和有联系的其他官方和非官方国际组织也可参与国际标准的制定工作对于信息技术和建立了一个联合技术委员会 即技术委员会的主要任务是制定国际标准 但在例外的情况下 技术委员会可以提出下列类型之一的技术报告类型虽然一再努力 但仍不能获得出版一项国际标准所需要的支持时类型所讨论的项目仍处于技术发展阶段类型技术委员会所收集到的数据不是来源于正式出版的国际标准 例如 目前工艺水平时类型和类型技术报告在出版后年内应提交复审 以决定是否将它们转变成国际标准类型技术报告不是务必要进行复审 除非它们提供的数据已被认为不再有效或已经没有用属于类型技术报告 它是由信息技术 联合技术委员会制定的引言软件生存期的所有阶段都要求编制文档 因此 文档编制和维护是必需的并且从软件的概念阶段连续作用到它废止文档编制开始于软件项目的初始阶段 并贯穿于软件的设计 开发 测试 安装 使用修改和增强仅当软件走到它的生命终点时才认为文档编制过程结束文档编制是任何软件开发项目成功的基础 并且文档的产生需要有时间 人工和资金的支撑管理的职责是保证这些资源有效地利用重要文档的标识以使软件产品成功开发并提高质量中 华 人 民 共 和 国 国 家 标 准软件文档管理指南国家技术监督局批准实施范围本标准为那些对软件或基于软件的产品的开发负有职责的管理者提供软件文档的管理指南本标准的目的在于协助管理者在他们的机构中产生有效的文档本标准涉及策略 标准 规程 资源和计划 管理者必须关注这些内容 以便有效地管理软件文档本标准期望应用于各种类型的软件 从简单的程序到复杂的软件系统 并期望复盖各种类型的软件文档 作用于软件生存期的各个阶段不论项目的大小 软件文档管理的原则是一致的对于小项目 可以不采用本标准中规定的有关细节管理者可剪裁这些内容以满足他们的特殊需要本标准是针对文档编制管理而提出的 不涉及软件文档的内容和编排引用标准下列标准所包含的条文 通过在本标准中引用而构成为本标准的条文本标准出版时 所示版本均为有效 所有标准都会被修订 使用本标准的各方应探讨使用下列标准最新版本的可能性计算机软件开发规范计算机软件产品开发文件编制指南软件工程术语定义本标准采用下列定义 其他定义见文档一种数据媒体和其上所记录的数据它具有永久性并可以由人或机器阅读通常仅用于描述人工可读的内容例如 技术文件 设计文件 版本说明文件文档 集文档编制一个或多个相关文档的集合文档计划一个描述文档编制工作方法的管理用文档 该计划主要描述要编制什么类型的文档 这些文档的内容是什么 何时编写 由谁编写 如何编写 以及什么是影响期望结果的可用资源和外界因素文档等级对所需文档的一个说明 它指出文档的范围 内容 格式及质量 可以根据项目 费用 预期用途 作用范围或其他因素选择文档等级软件产品软件开发过程的结果 并推出供用户使用的软件实体软件文档的作用管理依据任务之间联系的凭证质量保证培训与参考软件维护支持历史档案管理依据在软件开发过程中 管理者必须了解开发进度 存在的问题和预期目标每一阶段计划安排的定期报告提供了项目的可见性定期报告还提醒各级管理者注意该部门对项目承担的责任以及该部门效率的重要性 开发文档规定若干个检查点和进度表 使管理者可以评定项目的进度 如果开发文档有遗漏不完善 或内容陈旧 则管理者将失去跟踪和控制项目的重要依据任务之间联系的凭证大多数软件开发项目通常被划分成若干个任务 并由不同的小组去完成学科方面的专家建立项目 分析员阐述系统需求 设计员为程序员制定总体设计 程序员编制详细的程序代码 质量保证专家和审查员评价整个系统性能和功能的完整性 负责维护的程序员改进各种操作或增强某些功能这些人员需要的互相联系是通过文档资料的复制 分发和引用而实现的 因而 任务之间的联系是文档的一个重要功能大多数系统开发方法为任务的联系规定了一些正式文档分析员向设计员提供正式需求规格说明 设计员向程序员提供正式设计规格说明 等等质量保证那些负责软件质量保证和评估系统性能的人员需要程序规格说明 测试和评估计划 测试该系统用的各种质量标准 以及关于期望系统完成什么功能和系统怎样实现这些功能的清晰说明 必须制订测试计划和测试规程 并报告测试结果 他们还必须说明和评估安全 控制 计算 检验例行程序及其他控制技术这些文档的提供可满足质量保证人员和审查人员上述工作的需要培训与参考软件文档的另一个功能是使系统管理员 操作员 用户 管理者和其他有关人员了解系统如何工作以及为了达到他们的各自的目的 如何使用系统软件维护支持维护人员需要软件系统的详细说明以帮助他们熟悉系统 找出并修正错误 改进系统以适应用户需求的变化或适应系统环境的变化历史档案软件文档可用作未来项目的一种资源 通常文档记载系统的开发历史 可使有关系统结构的基本思想为以后的项目利用 系统开发人员通过审阅以前的系统以查明什么部分已试验过了 什么部分运行得很好 什么部分因某种原因难以运行而被排除 良好的系统文档有助于把程序移植和转移到各种新的系统环境中管理者的作用管理者严格要求软件开发人员和编制组完成文档编制 并且在策略 标准 规程 资源分配和编制计划方面给予支持管理者对文档工作的责任 管理者要认识到正式或非正式文档都是重要的 还要认识到文档工作必须包括文档计划 编写 修改 形成 分发和维护等各个方面管理者对文档工作的支持管理者应为编写文档的人员提供指导和实际鼓励 并使各种资源有效地用于文档开发管理者的主要职责建立编制 登记 出版系统文档和软件文档的各种策略把文档计划作为整个开发工作的一个组成部分建立确定文档质量 测试质量和评审质量的各种方法的规程为文档的各个方面确定和准备各种标准和指南积极支持文档工作以形成在开发工作中自觉编制文档的团队风气不断检查已建立起来的过程 以保证符合策略和各种规程并遵守有关标准和指南通常 项目管理者在项目开发前应决定如下事项要求哪些类型的文档提供多少种文档文档包含的内容达到何种级别的质量水平何时产生何种文档如何保存 维护文档以及如何进行通信如果一个软件合同是有效的 应要求文档满足所接受的标准 并规定所提供的文档类型 每种文档的质量水平以及评审和通过的规程制订文档编制策略文档策略是由上级 资深 管理者准备并支持的 对下级开发单位或开发人员提供指导 策略规定主要的方向 不是做什么或如何做的详细说明一般说来 文档编制策略陈述要明确 并通告到每个人且理解它 进而使策略被他们贯彻实施支持有效文档策略的基本条件文档需要复盖整个软件生存期在项目早期几个阶段就要求有文档 而且在贯穿软件开发过程中必须是可用的和可维护的 在开发完成后 文档应满足软件的使用 维护 增强 转换或传输文档应是可管理的指导和控制文档的获得和维护 管理者和发行专家应准备文档产品 进度 可靠性 资源 质量保证和评审规程的详细计划大纲文档应适合于它的读者读者可能是管理者 分析员 无计算机经验的专业人员 维护人员 文书人员等 根据任务的执行 他们要求不同的材料表示和不同的详细程度针对不同的读者 发行专家应负责设计不同类型的文档文档效应应贯穿到软件的整个开发过程中在软件开发的整个过程中 应充分体现文档的作用和限制 即文档应指导全部开发过程文档标准应被标识和使用应尽可能地采纳现行的标准 若没有合适的现行标准 必要时应研制适用的标准或指南应规定支持工具工具有助于开发和维护软件产品 包括文档因此尽可能地使用工具是经济的 可行的附录中的检查表为制定策略条款或评估现有策略条款的有效性和完整性提供帮助制订文档编制标准和指南在一个机构内部 应采用一些标准和指南软件生存期模型文档类型和相互关系文档质量这些标准和指南将决定如何实现文档任务 将提供一些准则以评价该机构内所产生的软件文档的完整性 可用性和适合性尽可能地采用现行的国家和国际标准 若现行的标准不适用 机构应制订自己的标准选择软件生存期模型现有的一些软件生存期模型 对于不同的阶段有不同词汇 从软件文档的观点来看 采用哪种模型都无关紧要 只要阶段和相应的文档是清晰定义的 已计划的 并且对于任何具体软件项目是能遵循的因此 管理者应选择一个软件生存期模型并保证该模型在他们机构内是适用的管理者将会发现所进行的阶段和相应任务的定义有助于监控软件项目的进展相应于特定阶段生成的文档可用作该阶段的评审 通过和完成的检验点 而这种检验应在下一阶段开始前进行规定文档类型和内容下面给出软件文档主要类型的大纲 这个大纲不是详尽的或最后的 但适合作为主要类型软件文档的检验表而管理者应规定何时定义他们的标准文档类型软件文档归入如下三种类别开发文档描述开发过程本身产品文档描述开发过程的产物管理文档记录项目管理的信息开发文档开发文档是描述软件开发过程 包括软件需求 软件设计 软件测试 保证软件质量的一类文档 开发文档也包括软件的详细技术描述 程序逻辑 程序间相互关系 数据格式和存储等开发文档起到如下五种作用它们是软件开发过程中包含的所有阶段之间的通信工具 它们记录生成软件需求 设计 编码和测试的详细规定和说明它们描述开发小组的职责通过规定软件 主题事项 文档编制 质量保证人员以及包含在开发过程中任何其他事项的角色来定义做什么 如何做和何时做它们用作检验点而允许管理者评定开发进度如果开发文档丢失 不完整或过时 管理者将失去跟踪和控制软件项目的一个重要工具它们形成了维护人员所要求的基本的软件支持文档而这些支持文档可作为产品文档的一部分它们记录软件开发的历史基本的开发文档是可行性研究和项目任务书需求规格说明功能规格说明设计规格说明 包括程序和数据规格说明开发计划软件集成和测试计划质量保证计划 标准 进度安全和测试信息产品文档产品文档规定关于软件产品的使用 维护 增强 转换和传输的信息产品的文档起到如下三种作用为使用和运行软件产品的任何人规定培训和参考信息使得那些未参加开发本软件的程序员维护它促进软件产品的市场流通或提高可接受性产品文档用于下列类型的读者用户他们利用软件输入数据 检索信息和解决问题运行者他们在计算机系统上运行软件维护人员他们维护 增强或变更软件产品文档包括如下内容用于管理者的指南和资料 他们监督软件的使用宣传资料 通告软件产品的可用性并详细说明它的功能 运行环境等一般信息 对任何有兴趣的人描述软件产品基本的产品文档包括培训手册参考手册和用户指南软件支持手册产品手册和信息广告管理文档这种文档建立在项目管理信息的基础上 诸如开发过程的每个阶段的进度和进度变更的记录软件变更情况的记录相对于开发的判定记录职责定义这种文档从管理的角度规定涉及软件生存的信息相关文档的详细规定和编写格式见确定文档的质量等级仅仅依据规章 传统的做法或合同的要求去制作文档是不够的 管理者还必须确定文档的质量要求以及如何达到和保证质量要求质量要求的确定取决于可得到的资源 项目的大小和风险 可以对该产品的每个文档的格式及详细程度作出明确的规定每个文档的质量必须在文档计划期间就有明确的规定文档的质量可以按文档的形式和列出的要求划分为四级最底限度文档级文档级文档适合开发工作量低于一个人月的开发者自用程序 该文档应包含程序清单 开发记录 测试数据和程序简介内部文档级文档级文档可用于在精心研究后被认