计算机软件文档编制规范

中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute计算机软件文档编制规范中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute修订背景２修订依据３新老版本的差异４新版标准结构５文档编制过程６文档编制要求７文档编制格式８小结中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute计算机文档编制一、本标准修订的背景ＧＢ／Ｔ８５６７－１９８８版是参考英国某公司的文档标准，结合当时国内软件开发的经验，而且主要是针对瀑布模型的开发方法而制定的。该标准的发布与实施对我国上世纪八十年代、九十年代的软件开发发挥了重要作用。但随着时间的推移，软件工程技术的发展与提高，目前来看，８８版已经不适应软件产业发展的需要，因此修订ＧＢ／Ｔ８５６６－１９８８版势在必行。中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute计算机文档编制二、GB/T8567-2019制定的依据主要依据：•ＧＢ／Ｔ８５６６－２００１信息技术软件生存周期过程•ＳＪ／Ｔ２０７７８－２０００软件开发与文档编制•ＩＳＯ／ＩＥＣ１５９１０：１９９９信息技术软件用户文档过程中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute计算机文档编制三、ＧＢ／Ｔ８５６７新老版本的主要差异•ＧＢ／Ｔ８５６７－１９８８主要适用于瀑布模型开发方法•ＧＢ／Ｔ８５６７－１９８８给出了１４种文档的编制格式要求：１）可行性研究报告２）项目开发计划３）软件需求说明书中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute计算机文档编制ＧＢ／Ｔ８５６７新老版本的主要差异４）数据要求说明书５）概要设计说明书６）详细设计说明书７）数据库设计说明书８）用户手册９）操作手册１０）模块开发卷宗１１）测试计划１２）测试分析报告１３）开发进度月报１４）项目开发总结报告中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute计算机文档编制ＧＢ／Ｔ８５６７新老版本的主要差异ＧＢ／Ｔ８５６７－２００6原则上适用于各种类型的开发方法ＧＢ／Ｔ８５６７－２００6描述了文档编制过程ＧＢ／Ｔ８５６７－２００6给出２５种文档的编制格式要求１）可行性分析（研究）报告２）软件开发计划３）软件测试计划４）软件安装计划中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute计算机文档编制ＧＢ／Ｔ８５６７新老版本的主要差异５）软件移交计划６）运行概念说明７）系统／子系统需求规格说明８）接口需求规格说明９）系统／子系统设计（结构设计）说明１０）接口设计说明１１）软件需求规格说明１２）数据需求说明１３）软件（结构）设计说明中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute计算机文档编制ＧＢ／Ｔ８５６７新老版本的主要差异１４）数据库（顶层）设计说明１５）软件测试说明１６）软件测试报告１７）软件配置管理计划１８）软件质量保证计划１９）开发进度月报２０）项目开发总结报告中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute计算机文档编制ＧＢ／Ｔ８５６７新老版本的主要差异２１）软件产品规格说明２２）软件版本说明２３）软件用户手册２４）计算机操作手册２５）计算机编程手册•另外给出了面向对象的１０种文档的编制格式要求中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute计算机文档编制四、ＧＢ／Ｔ８５６７－２００6标准结构１、范围２、规范性引用文件３、术语和定义４、缩略语５、文档（编制）过程６、文档编制要求７、文档编制格式附录Ａ面向对象软件的文档编制中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute计算机文档编制五、文档（编制）过程5.1概述有两种主要类型的标准：a.产品标准，它规定产品的特征和功能需求；b.过程标准，它规定开发产品的过程。应用程序和计算机软件的复杂性日益增加，使得给使用计算机的用户提供完整的、正确的和易懂的文档的需要更加迫切。本标准通过规定影响软件文档的质量的活动（做什么和由谁做），提供达到这些目的的工具。中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute计算机文档编制文档常常是关心在软件已经实现后做些什么。然而，为了质量，软件文档编制应作为整个软件生产过程的一部分。过程计划应把文档计划包括在内。本标准也给用户和客户提供工具以保证文档过程实施。本标准的主要活动之一是建立开发文档的广泛计划。这是必须的，因为有计划，文档编制的质量会更好，过程的效率会更高。为遵循本标准，计划必须包括风格规格说明。本标准不规定风格规格说明的内容（即不规定具体的布局和字体），但它规定风格规格说明必须覆盖什么。本标准也规定何种信息对于文档管理者是可用的和谁做评审和再生产文档。中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute文档（编制）过程的关注点•文档编制计划•文档开发（编制）•文档评审中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute概要文档管理者应准备一文档计划，此计划规定在文档创建中要执行的工作。此文档计划应经需方正式同意，以预示它完全覆盖了需方的要求。l文档计划通常将覆盖整个文档系列。文档计划应正式地描述计划的文档的范围和限制，以及重要的文档分析和设计决定。也应规定在文档开发期间实现的过程和控制。中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute计算机文档编制文档计划应包括（但不限于）以下内容：a）计划的文档的工作名称、目的、范围和限制。b）文档的预定的读者，和使用的目的。c）文档内容的草案表，带有估计的页数和其他媒体的等效细节。d）交付：打印副本数，是否提供电子副本，磁盘和文件格式（包括软件版本）和在何处交付。e）版权的拥有者和任何其他所有权。l这是复杂的问题，应在合同中规定。中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute）适当处，包括每个文档的安全或机密级。g）管理文档开发过程的步骤和控制，包括存储、检索、后备、处理和质量保证（若要求）。h）所用的生产方法、工具和工具版本。i）文档开发人员所在的队伍的结构，任选地，包括队伍选择计划。l在文档编写和生产的不同阶段中的工作人员，需要不同的技巧。编写人员可能要求对正在编写的系统有好的知识加上写文档的经验；编辑人员可能要求有编辑经验而对系统知识无要求；版面艺术家可能对所用的版面工具外，无任何知识要求。中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute）项目依赖。k）所要求的人时和成本。l）项目资源需求，包括需方提供的信息和其他资源。m）在软件开发期间，软件变更传送信息给文档管理者的方法。n）文档的变更控制和维护的计划（任选）。o）实现后评审的计划（任选）。中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute）显示适当的里程碑的时间表，包括：1）文档计划批准；对于文档的每一项应重复。l文档计划宜2）每个草案的准备、评审和改正；3）可用性测试；4）打印、装订和发布。若适当，这些活动的每一个在文档的开发开始以前准备与批准，以保证所有部门同意目标和所用的方法。批准后，计划宜尽可能广泛地分发；分发宜包括所有文档开发人员和可能包括需方人员及子合同方。中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute文档计划控制在正式同意后，文档管理者应控制文档计划和它的发布。文档管理者应保持一份文档计划副本的分发的清单。若以后文档计划变更了（得到文档管理者和需方的同意），文档管理者应保证所有得到文档计划副本的人员，应得到变更通知。l因为，计划的过时的副本可能引起问题，文档管理者宜禁止计划的未控制的副本并制订计划的所有副本已经更新的审核过程。中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute文档开发按文档计划规定进行文档开发。通常，在进行文档开发前，要规定文档的格式（风格）。在软件的开发和管理过程中需要那些文档，每种文档的规范在下面说明。中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute概述本节规定文档评审的要求和相关活动。本节主要以用户文档的评审为例说明。对于开发文档的评审，由供方组织和实施。而批准由开发组织的上级技术机构实施。更要着重经常性的、非正式的注重实效的评审。不是要追求形式。中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute计算机文档编制用户文档的评审应由需方实现，包括当需要时与文档管理者讨论。l评审的目的是保证提交的材料是完整的和正确的并满足了在合同和文档计划中定义的需方的需要。评审宜由合适的有资格的人员执行，这些人员被授权请求变更和批准文档的内容。l需方宜限止评审人员数为评审功能所必需的那些。需方在批准每个用户文档草案之前，应保证文档的安全和合法。为评审交付的文档应包括从文档管理者来的说明书，说明评审的目的和评审员的职责。中国电子技术标准化研究所@byChinaElectronicsStandardizationInstitute：在需方和文档管理者之间在整个开发过程期间维持良好的通信会提高文档的质量并利于评审成功。这宜包括非正式的讨论和尽早地提供样板或初始材料给需方。l注2：在要求的变更超出了合同和文档计划的范围时，需要变更合同。l注3：评审过程不免除文档管理