【国家标准】 工业控制计算机系统 软件 第3部分：文档管理指南

ICS 25.040.40
中华人民共和国国家标准
GB/T26805.3—2011
工业控制计算机系统
第3部分：文档管理指南
Industrial control computer systemSoftware-Part 3 :Guidelines for the document management2011-07-29发布
中华人民共和国国家质量监督检验检疫总局中国国家标准化管理委员会
2011-12-01实施
GB/T26805.3—2011
规范性引用文件
术语和定义
4软件文档
主要功能
工作文档
产品文档
用户软件包文档
5软件文档的计划管理
基本任务
管理要点
6软件文档的质量管理
软件文档的质量分级及质量要求6.1
6.2软件文档的复审
软件文档的配置管理
管理要点总结
软件生命周期的定义及阶段划分附录A（规范性附录）
A.1软件生命周期的定义
A.2软件定义阶段
软件开发阶段
A.4运行维护阶段
软件生命周期各个阶段应当产生的主要软件文档附录B（规范性附录）
图1软件文档分级与对应文档
图B.1软件生命周期各个阶段应当产生的重要软件文档示意10
GB/T26805《工业控制计算机系统第1部分：评价体系；
第2部分：测试方法；
第3部分：文档管理指南；
第4部分：工程化文档规范；
一第5部分：用户软件包文档。
本部分是GB/T26805的第3部分。前言
软件》分为以下部分：
本部分的附录A和附录B为规范性附录。本部分由中国机械工业联合会提出本部分由全国工业过程测量和控制标准化技术委员会（SAC/TC124）归口。本部分负责起草单位：西南大学。GB/T26805.3—2011
本部分参加起草单位：深圳市研祥软件技术有限公司、北京研华兴业电子科技有限公司、中国计算机学会工业控制计算机专业委员会本部分主要起草人：吕静、杨颂华、张为群、张渝、祁虔。本部分参加起草人：陈志列、刘志永、刘学东、刘永池、杨孟飞。I
1范围
工业控制计算机系统软件
第3部分：文档管理指南
GB/T26805.3—2011
GB/T26805的本部分规定了工业控制软件文档管理的基本任务和管理要点，为项目管理者实施该类文档的管理提供指南
本部分适用于工业控制计算机系统的软件文档管理。2规范性引用文件
下列文件中的条款通过GB/T26805的本部分的引用而成为本部分的条款。凡是注日期的引用文件，其随后所有的修改单（不包括勘误的内容）或修订版均不适用于本部分，然而，鼓励根据本部分达成协议的各方研究是否可使用这些文件的最新版本。凡是不注日期的引用文件，其最新版本适用于本部分。
GB/T11457一2006信息技术软件工程术语GB/T26805.4一2011工业控制计算机系统软件第4部分：工程化文档规范GB/T26805.5一2011工业控制计算机系统软件第5部分：用户软件文档3术语和定义
GB/T11457一2006中确立的以及下列术语和定义适用于GB/T26805的本部分。3.1
文档document
-种数据媒体和其上所记录的数据。它具有永久性并可以由人或机器阅读。3.2
用户user
使用软件求解某一问题的技术人员；a）
b）实际使用软件产品或操作运行软件的组织、单位或个人。3.3
产品文档
productdocumentation
软件项目开发过程中，应当编制的各种技术资料或技术管理资料。3.4
工作文档workdocumentation
软件项目开发过程中，所填写的或使用过的各种图表或文字资料。3.5
用户需求
userrequirement
用户所期望的软件产品的全部性能、功能和限制。它主要包括对软件产品的功能要求、性能要求，如实时性、可靠性和可维护性要求以及安全保密要求，还包括在开发费用、时间、进度和可用资源等方面的限制。
评审review
软件项目开发中的一个重要环节。它是对某个开发产品或过程进行的全面检查、鉴定和认可。目1
GB/T 26805.3—2011
的在于尽可能早地发现错误，将实现和要求进行统一和协调。3.7
配置管理configurationmanagement标识和确定系统中配置项的过程，在系统整个生存周期内控制这些项的投放和更动，记录并报告配置的状态和更动要求，验证配置项的完整性和正确性，3.8
软件产品库softwareproductionlibrary在软件生命周期的集成与系统测试阶段结束后，用于存放作为最终产品而交付给用户运行或现场安装的软件库。
软件文档softwaredocumentation以人们可读的形式出现的技术数据和信息，包括计算机列表和打印输出，它们描述或规定软件设计或细节，说明软件具备的能力，或为使用软件以便从软件系统得到所期望的结果而提供的操作指令。软件文档
4.1概述
有关软件文档概述如下：
软件文档是由制造商提供的、软件产品生命周期中的所有文档；a）
b）软件文档归人工作文档和产品文档两类；c）
软件文档是与软件产品有关的可读文件，用以描述和记载软件产品生命周期各阶段的活动及结果；
d）软件文档的表现形式可以是文字、表格、图形和音像等；软件文档中包含描述硬件访问接口（如寄存器、引脚定义、端口、组态、中断等）的文档，以及工e)
业现场对软件产品的要求（如可靠性、实时性、安全性等）：软件文档可以记载于多种媒体（例如光盘、磁盘、磁带、非易失性存储器和纸等介质）上，具有持f
久性，便于保存、修改、传输和自动化管理；g）软件文档可以复制；软件文档可随软件升级而更新（经授权许可）。4.2主要功能
4.2.1概述
软件文档应该具备以下主要功能：实现软件管理的依据；
b）实现任务之间联系的凭证；
提供使用须知与说明；
d）提供质量保证支持；
e）作为历史资料；
f）提供产权声明。
4.2.2实现软件管理的依据
软件文档记录了软件产品在生命周期内各阶段的活动情况，为各阶段的检查、评审和管理提供依据，同时，软件文档记录的技术信息，可以为软件产品开发的技术管理提供依据4.2.3实现任务之间联系的凭证
软件开发项目的任务主要由以下各类人员承担：软件项目管理人员；
b）提出用户需求及项目要点的专家；c）
系统分析师；
软件项目的程序设计师；
提供程序代码的程序员；
f）车
软件测试员；
质量保证专家和审核人员；
h）改进操作或开发加强和扩展产品性能的维护程序员，GB/T26805.3—2011
根据软件工程化的要求，软件文档是以上各类人员之间通信和交流的凭证，从而实现任务间的联系。
4.2.4提供使用须知与说明
软件文档能够提供使用须知与说明，告知系统管理人员、操作人员、用户及维护人员系统怎样工作、如何正确使用系统去实现他们的目标，同时可实现对用户的技术培训，帮助用户尽快掌握软件产品的使用方法。
4.2.5提供质量保证支持
软件文档必须保证向质量保证、维护和审核人员提供执行其任务时所需要的各种质量标准以及关于期望系统完成什么功能和系统怎样实现这些功能的清晰说明；必须制订测试计划和测试规程，并报告测试结果；还必须说明和评估相关的控制、计算、检验例行程序及其他技术。4.2.6作为历史资料
将软件文档用作将来进行项目开发的一种资源。通常文档记载系统的开发历史，可使有关系统结构的基本思想和开发经验为以后的项目利用。良好的系统文档有助于把程序移植和转移到各种新的系统环境中。
4.2.7提供产权声明
软件文档包含软件产品的评测报告、版权、著作权、知识产权等相关资料。4.3工作文档
4.3.1工作文档的目的此内容来自标准下载网
工作文档的目的包括：
a）工作文档主要记录需求、设计、程序和测试方面有关决定的细节；b）工作文档明确划分全体开发人员的职责范围，规定每一个人应该做什么，使他们能够各司其职；
c）工作文档明确规定检查要点和进度，便于项目管理者评估项目的进展情况；d）工作文档记录项目开发的历史，为开发后续项目提供参考4.3.2工作文档的内容
工作文档可分为开发文档和管理文档。开发文档描述项目开发过程本身，以开发所涉及的工具、方法等技术为主；管理文档描述开发阶段划分，各开发阶段的任务确定，以及如何实现各个阶段的衔接，记录进度、变更和职责定义、评定等管理工作。工作文档内容包括：
可行性研究报告；
软件项目开发计划书；
一软件质量保证计划书；
软件配置管理计划书；
一安全与控制信息规格说明；
备忘录或改变控制形式的记录
GB/T26805.3—2011
实际的工作文档可以包括上述文档中的部分或全部。根据项目开发的特点，还可以产生新的工作文档。
工作文档的内容与格式应符合GB/T26805.4一2011的有关规定。4.4产品文档
4.4.1产品文档的目的
产品文档提供有关软件产品的有效使用、运行、维护、更新方面的信息，包括：a）向程序员、操作员和最终用户提供所需的文档资料；b）为项目管理者实现科学管理提出的各种资料，以监控产品的开发与应用；c）
说明产品可用性、为促进产品推广而具体阐述应用范围的宣传资料；d）向关心软件产品的人们提供的、用以描述产品特点的信息交流资料。4.4.2产品文档的范围
产品文档一般包括：
软件需求规格说明书；
数据需求说明书；
系统（子系统)设计说明书；
软件概要设计说明书；
软件详细设计说明书；
数据库设计说明书；
软件模块规格说明书；
技术评审；
测试计划；
测试分析报告；
用户手册；
操作手册：
程序维护手册；
安装实施过程；
用户培训资料及宣传资料
实际的产品文档可以包括上述文档中的部分或全部，根据项目开发的特点，还可以产生新的产品文档。
产品文档的内容与格式应符合GB/T26805.4一2011的有关规定。4.5用户软件包文档
用户软件包文档见GB/T26805.5—2011。软件文档的计划管理
5.1基本任务
软件文档计划管理的基本任务是：明确划分软件生存周期的各个阶段；a）
b）确定每个阶段应当编制的软件文档；c）提出软件文档编制计划，并监督实施。5.2管理要点
5.2.1软件生命周期的阶段划分
附录A给出了软件生命周期的定义及阶段划分的常用方法。4
GB/T26805.3—2011
对于一个具体的软件开发项目，软件生命周期的各个阶段应当如何划分，项目管理者应着重考虑以下两个因素：
5.2.1.1标识阶段的名称可以改变随着所用开发方法的不同，开发项目的不同，阶段名称允许有相当大的差异。但必须坚持阶段的明确划分，以便分段实施、加强管理。5.2.1.2阶段划分具有灵活性
阶段划分的详细程度取决于软件项目的重要性、复杂程度、使用频度、软件规模、技术水平和成败风险等诸种因素。项目管理者应根据软件项目的实际情况进行权衡。5.2.2文档编制应考虑的因素
5.2.2.1总则
坚持在软件生存周期的各个阶段必须编制对应的软件文档，是项目管理者实施文档计划管理的另一个管理要点。然而，一个具体的软件开发项目究竟需要编制哪些软件文档，是由多种因素决定的，项目管理者必须充分地予以考虑
5.2.2.2必要性
为了保证软件项目开发工作的顺利进行，作为软件生存周期各个阶段工作完成的重要标志，开发人员必须按开发阶段的要求认真编制相应的软件文档与软件生存周期各个阶段对应的软件文档见附录B。5.2.2.3重复性
在确定软件文档种类时，应保持每种文档的独立性，但充许内容上存在某些重复，以适合不同读者的需要。
5.2.2.4灵活性
和软件生命周期的阶段划分具有灵活性一样，需要编制的文档种类也具有灵活性。一般说来，当软件项目的复杂程度、软件规模和成败风险增大时，软件文档的种类、详细程度将随之增加。反之，可适当减少，为了避免在软件项目开发中文档编制的不足或过度，项目管理者可主要根据软件规模去确定需要编制哪些软件文档。
软件规模可分为以下三级：
a）小规模软件——源程序行数少于3000行的软件；b）中规模软件——源程序行数为3000～30000行的软件；c）大规模软件一一源程序行数为30000行以上的软件。对软件开发项目文档编制的要求亦相应地分为三级，如图1所示。根据图1,某些文档可以是某种文档的扩展和细分。在最简单的情况下，可合并成软件需求说明与开发计划、软件设计说明、使用说明和项目开发总结四种文档。而在软件规模特别庞大的情况下，可进一步细分为更多的软件文档5
GB/T 26805.3—2011
小规模软件
软件需求说明
与开发计划
软件设计说明
使用说明
项目开发总结
5.2.3软件文档编制计划
5.2.3.1总则
中规模软件
项目开发计划
软件需求说明
软件计划
软件设计说明
使用说明
开发进度定期报告
项目开发总结
评查报告
图1软件文档分级与对应文档
大规模软件
可行性研究报告
软件项目开发计划
软件质量保证计划
软件配置管理计划
软件需求规格说明
数据需求说明
测试计划
软件概要设计说明
软件详细设计说明
数据库设计说明
软件模块规格说明
用户手册
操作手册
安装实施手册
开发进度定期报告
项目开发阶段总结
评查报告
软件文档编制计划可以是整个项目计划的一部分，也可以是一个独立的文档。它作为说明文档重要性的具体资料，也作为项目管理者的备忘录，是型式检查、复审和验收的重要依据。文档编制计划应包括对以下几个问题的陈述：文档内容与型式；
文档格式与标示；
文档编制的进度；
开发人员的职责范围
5.2.3.2文档内容与形式
文档内容着重于功能方面的说明，告诉软件开发人员本阶段“做什么”。现就与产品文档有关的几个问题规定如下。
5.2.3.2.1程序员文档
主要包括以下内容：
a）总则必须向程序员提供编码、维护或强化现存软件所需要的全部信息。例如有关程序逻辑、6
GB/T26805.3—2011
数据存储规格说明与功能描述方面的图解和说明。通过这些信息使程序员明白：假设软件干什么，而当假设成立时软件怎样去干。b）程序说明软件的开发管理必须保证开发程序员能够应用程序设计语言的方便在编码时插入程序说明。并发程序员应将这些说明准备好，以便实现程序的编码以及在修改程序时加以利用。在程序说明中，每个程序模块都应包含模块在逻辑、目的和基本原理方面的叙述，还可能包括有关子程序文档和条件处理方面的叙述。对于不常见的编码而言，还可能需要具体码串的具体说明。例如为求解某一问题的算法，就可以将阐明算法来源、所需数据、计算结果以及结果怎样为程序所用方面的说明放在它的前面。c）图示需要对程序逻辑进行逐条描述，对出现在一个程序或一个系统以及出现在用以说明程序逻辑流程图中的数据流要进行描述，向维护程序员展示需由他们进行维护的程序段逻辑，以及展示这种程序段逻辑与系统中其他程序或模块有怎样的关系。d）存储规格说明必须向维护程序员提供数据存储在何处，以及按何种形式进行存储方面的信息。
形式系统文档
维护程序员有时需要比程序说明、图示和存储规格说明更多的信息。他们还需要详细的文字说明，更为完善的软件产品，常常需要有对系统或程序给予文字说明的形式文档。
5.2.3.2.2系统事务管理员/操作员文档为了运行系统的硬件和软件，需要了解支持系统运行的各种因素。系统事务管理员/操作员文档告知与此有关的各种信息，包括：a）
批量作业的进度和名称、项目的运行时间：数据存储需求以及程序如何取得所存储的数据；b）
所用设备；
项目的系统联机应用时数；
调试、检修指南。
5.2.3.2.3用户培训和参考资料
没有足够用户信息的产品文档是不完备的。用户至少需要两类信息：培训信息一一帮助用户迅速成为系统应用方面的专家；a）
b）参考资料——帮助用户找到回答有关系统应用具体问题的答案。此外，用户可能希望知道他们在使用系统时怎样才能与系统的整个工作相适应，为此，产品文档还应提供与此有关的各种信息
满足这些信息需求的文档，其格式可以有所不同，可以是形式化、半形式化或非形式化的，由项目管理者最终决定。
5.2.3.2.4宣传/信息交流文档
包括以下几个方面：
a）总则这类文档的重要意义在于：增加系统的满意程度，使用户能比较容易地使用产品；争取潜在用户，使产品获得推广应用的可能性。宣传/信息交流文档有以下几种类型。b）产品说明产品说明应以简短的形式去总结系统的特点，指出系统的硬件和软件需求c）情况通报作为一种专供软件项目开发人员使用的内部文档，情况通报告知项目的进展情况使全体开发人员作好交付产品（包括阶段产品）的准备。5.2.3.3文档格式与标识
文档的编制格式应符合GB/T26805.4一2011的有关规定。7