计算机软件文档编制规范(I)

'计算机软件文档编制规范中标软件公司周明德 5文档过程 5.1概述有两种主要类型的标准：a.产品标准，它规定产品的特征和功能需求；b.过程标准，它规定开发产品的过程。文档标准就是一种过程标准。应用程序和计算机软件的复杂性日益增加，使得给使用计算机的用户提供完整的、正确的和易懂的文档的需要更加迫切。本标准通过规定影响软件文档的质量的活动（做什么和由谁做），提供达到这些目的的工具。 文档常常是关心在软件已经实现后做些什么。然而，为了质量，软件文档编制应作为整个软件生产过程的一部分。过程计划应把文档计划包括在内。本标准也给用户和客户提供工具以保证文档过程实施。本标准的主要活动是建立开发文档的广泛计划。这是必须的，因为有计划，文档编制的质量会更好，过程的效率会更高。本标准也规定何种信息对于文档管理者是可用的和谁做评审及谁生产文档。 本标准遵循GB/T8566－2001《信息技术软件生存周期过程》。为其开发过程和管理过程中的主要文档规定了编制规范。本标准是按文档由专门的文档管理人员和文本编写人员的模式规定的。具体的项目可根据具体情况安排。文档过程的活动应按图5－1中的顺序执行。 其中，有两个阴影框。在一个阴影框中的所有活动应在下一个阴影框中的活动开始之前完成。在阴影框中的活动可以并行执行。虚线指示可能的重复。在文档的最小内容已经由需方规定的情况下，这宜由文档管理者在文档计划开发期间纳入总数中。 5.2源材料准备需方应允许文档管理者访问以下内容：a）所有有关的规格说明、记录格式、屏幕和报告布局、CASE工具输出和文档的准备所需要的任何其他的信息；b）若可用，软件的操作副本；c）软件的分析员和程序员，以及及时和确切地解答由文档开发人员提出的问题；d）若可能，访问典型的用户（为了做读者分析和可用性测试）。为了增加对产品和它的读者的了解，对软件开发人员的访问是必要的但使这样的访间保持到最小是文档管理者的责任。 不管文档管理者是否是软件的开发者，需方应提供适用的标准、风格和格式指南和其他相关的材料（除非，通常可用的）。文档管理者应分发这些材料至需要它的文档开发人员。保证需方交付给文档管理者的所有材料，当交付时，是完整的和正确的且在交付后保持是最新的，这是需方的责任。需方保证，提供的材料没有一个违反任何其他部门的知识产权。 文档管理者应采取所有有理由的步骤，以保证由需方提供的材料保持在很好的状态，应保证需方要求的信息安全并在文档项目完成后，所有材料返回给需方。在某些情况下，不是所有材料需要返回；这应在合同中定义。在某些情况下，由需方传送给文档管理者的材料要求保持机密的和安全的。合同宜规定对于传送给文档管理者的材料，需方要求文档管理者的机密和安全等级。 5.3文档计划5.3.1概要文档管理者应准备一文档计划，此计划规定在文档创建中要执行的工作。此文档计划应经需方正式同意，以预示它完全覆盖了需方的要求。文档计划应正式地描述计划的文档的范围和限制，以及重要的文档分析和设计决定。也应规定在文档开发期间实现的过程和控制。 文档计划应包括（但不限于）以下内容：a）计划的文档的工作名称、目的、范围和限制。b）文档的预定的读者，和使用的目的。c）文档内容的草案表，带有估计的页数和其他媒体的等效细节。d）交付：打印副本数，是否提供电子副本，磁盘和文件格式（包括软件版本）和在何处交付。e）版权的拥有者和任何其他所有权。 f）适当处，包括每个文档的安全或机密级。g）管理文档开发过程的步骤和控制，包括存储、检索、后备、处理和质量保证（若要求）。h）所用的生产方法、工具和工具版本。i）文档开发人员所在的队伍的结构，任选地，包括队伍选择计划。 j）项目依赖。k）所要求的人时和成本。l）项目资源需求，包括需方提供的信息和其他资源。m）在软件开发期间，软件变更传送信息给文档管理者的方法。n）文档的变更控制和维护的计划（任选）。o）实现后评审的计划（任选）。 p）显示适当的里程碑的时间表，包括：1）文档计划批准；2）每个草案的准备、评审和改正；3）可用性测试；4）打印、装订和发布。若适当，这些活动的每一个对于文档的每一项应重复。文档计划宜在文档的开发开始以前准备与批准，以保证所有部门同意目标和所用的方法。批准后，计划宜尽可能广泛地分发；分发宜包括所有文档开发人员和可能包括需方人员及子合同方。 5.3.2文档计划控制在正式同意后，文档管理者应控制文档计划和它的发布。文档管理者应保持一份文档计划副本的分发的清单。若以后文档计划变更了（得到文档管理者和需方的同意），文档管理者应保证所有得到文档计划副本的人员，应得到变更通知。因为，计划的过时的副本可能引起问题，文档管理者宜禁止计划的未控制的副本并制订计划的所有副本已经更新的审核过程。 5.4文档开发按文档计划规定进行文档开发。通常，在进行文档开发前，要规定文档的格式（风格）。在软件的开发和管理过程中需要那些文档，每种文档的规范在下面说明。 5.5评审5.5.1概述本节规定文档评审的要求和相关活动。本节主要以用户文档的评审为例说明。对于开发文档的评审，由供方组织和实施。而批准由开发组织的上级技术机构实施。更要着重经常性的、非正式的注重实效的评审。不是要追求形式。 用户文档的评审应由需方实现，包括当需要时与文档管理者讨论。l评审的目的是保证提交的材料是完整的和正确的并满足了在合同和文档计划中定义的需方的需要。评审宜由合适的有资格的人员执行，这些人员被授权请求变更和批准文档的内容。l需方宜限止评审人员数为评审功能所必需的那些。需方在批准每个用户文档草案之前，应保证文档的安全和合法。为评审交付的文档应包括从文档管理者来的说明书，说明评审的目的和评审员的职责。 注1：在需方和文档管理者之间在整个开发过程期间维持良好的通信会提高文档的质量并利于评审成功。这宜包括非正式的讨论和尽早地提供样板或初始材料给需方。注2：在要求的变更超出了合同和文档计划的范围时，需要变更合同。注3：评审过程不免除文档管理者，他们的责任是试图尽可能保证文档的精确和完整。注4：从评审的结果而来的需方的评论结果宜用或是加上标记的草案或用有适当的参考的方式写评论。需方宜保持变更的副本为了与下一草案相比较。评论应使文档开发人员能实现所要求的变更而不需要评审人员的进一步解释。注5：对于大的、复杂的系统或正在写文档时系统仍在开发，可能需要多于两次草案和一次校样。在这样情况下，最多的草案数宜在需方和文档管理者之间同意并在文档计划中规定。 5.5.2文档计划评审此评审的目的应保证文档计划定义的文档，当完成时，既满足开发过程的需要也满足需方在合同中规定的的文档目标。需方同意文档计划，是同意在计划中定义的用户文档的所有可交付的特征。注：需方宜放注意至在内容的草案表中展示的文档的结构、完整性和可用性。只要适当，文档计划宜在第一个草案开始工作之前评审和批准。 5.5.3第一个草案评审第一个草案应包含如在文档计划中描述的文档体，加上内容表，附录和词汇。在使用自动索引工具处，生成的索引包含位置参照。标点符号、风格和版面应如在文档计划中描述的。文档的第一个草案的评审目的是核查文档的技术正确性和完整性，以保证草案满足文档计划的目标。标点符号、风格和版面应如在文档计划中定义的。 在批准第一个草案中，除了要求的变更外，评审批准技术正确性、结构清楚性和文档的完整性。注1：第一个草案宜在交付前编辑。这有两个理由：a）这保证评审者不分心于改正印刷的和版面的错误；b）保证由编辑过程引起的任何技术错误被评审者捕获。注2：草案应针对在文档计划中批准的目标、读者定义、内容表和其他特征进行评审。在带有评论的第一个草案返回前，宜确认，若草案完全改正了，将满足文档计划的要求。 5.5.4第二个草案评审第二个草案应包在第一个草案评审中同意的所有变更且应以尽可能接近最后的形式包括在文档计划中定义的可交付的内容。此评审的目的是核查在第一个草案中的内容已经正确实现。在第二个草案的批准中，除了草案的物理形式外，批准文档的所有方面。草案的物理形式可能与可交付的不精确相同。注：在批准第二个草案前，宜确认草案（包含评审对草案的评论）已经准备好批准。 5.5.5校样评审校样应包括在第二个草案评审中同意的所有变更。此评审的目的是核查对第二个草案的评论已正确实现。任何不正确实现的评论应迅速地通知文档管理者，他们应相应地修改文档并返回可替换部分的副本，用于进一步评审。由批准证明，被接受的文档已准备好生产。 5.6与其他公司的文档开发子合同文档管理者应保证子合同的文档遵循本标准，遵循文档计划和合同。在子合同的文档中，文档管理者作为本标准的‘需方’而子合同承担者作为‘文档管理者’。注：文档管理者应与子合同承担者有规定本标准的协议。 6文档编制要求 6.1软件生存周期与各种文档的编制在计算机软件的生存周期中，一般地说，应该产生以下一些基本文档。可行性分析（研究）报告；软件（或项目）开发计划；软件需求规格说明；接口需求规格说明；系统／子系统设计（结构设计）说明；软件（结构）设计说明； 接口设计说明；数据库（顶层）设计说明；（软件）用户手册；操作手册；测试计划；测试报告； 软件配置管理计划；软件质量保证计划；开发进度月报；项目开发总结报告；软件产品规格说明；软件版本说明等。 本标准将给出这些文档的编制规范，同时，本标准也是这些文档的编写质量的检验准则。一般地说，一个软件总是一个计算机系统（包括硬件，固件和软件）的组成部分。鉴于计算机系统的多样性，本标准一般不涉及整个系统开发中的文档编制问题，本标准仅仅是软件开发过程中的文档编制指南。对于使用文档的人员而言他们所关心的文件的种类随他们所承担的工作而异。 管理人员：可行性分析（研究）报告，项目开发计划，软件配置管理计划，软件质量保证计划，开发进度月报，项目开发总结报告； 开发人员：可行性分析（研究）报告，项目开发计划，软件需求规格说明，接口需求规格说明，软件（结构）设计说明，接口设计说明书，数据库（顶层）设计说明，测试计划，测试报告； 维护人员：软件需求规格说明，接口需求规格说明，软件（结构）设计说明，测试报告， 用户：软件产品规格说明，软件版本说明，用户手册，操作手册。本标准规定了在软件开发过程中文档编制的要求，这些文档从使用的角度可分为用户文档和开发文档两大类。其中，用户文档必须交给用户。用户应该得到的文档的种类和规模由供应者与用户之间签订的合同规定。 如前所述，软件，从出现一个构思之日起，经过软件开发成功投入使用，直到最后决定停止使用并被另一项软件代替之时止，被认为是该软件的一个生存周期，一般地说这个软件生存周期可以分成以下六个阶段： 可行性与计划研究阶段；需求分析阶段；设计阶段；实现阶段；测试阶段；运行与维护阶段。 在可行性分析（研究）与计划阶段内，要确定该软件的开发目标和总的要求，要进行可行性分析、投资━收益分析、制订开发计划，并完成应编制的文档。在需求分析阶段内，由系统分析人员对被设计的系统进行系统分析，确定对该软件的各项功能、性能需求和设计约束，确定对文档编制的要求，作为本阶段工作的结果，一般地说软件需求规格说明（也称为：软件需求说明、软件规格说明）、数据要求说明和初步的用户手册应该编写出来。 在设计阶段内，系统设计人员和程序设计人员应该在反复理解软件需求的基础上，提出多个设计，分析每个设计能履行的功能并进行相互比较，最后确定一个设计，包括该软件的结构、模块（或CSCI）的划分、功能的分配，以及处理流程。在被设计系统比较复杂的情况下，设计阶段应分解成概要设计阶段和详细设计阶段两个步骤。在一般情况下，应完成的文档包括：结构设计说明、详细设计说明和测试计划初稿。 在实现阶段内，要完成源程序的编码、编译（或汇编）和排错调试得到无语法错的程序清单，要开始编写进度日报、周报和月报（是否要有日报或周报，取决于项目的重要性和规模），并且要完成用户手册、操作手册等面向用户的文档的编写工作，还要完成测试计划的编制。在测试阶段：该程序将被全面地测试，已编制的文档将被检查审阅。一般要完成测试分析报告。作为开发工作的结束，所生产的程序、文档以及开发工作本身将逐项被评价，最后写出项目开发总结报告。 在整个开发过程中（即前五个阶段中），开发集体要按月编写开发进度月报。在运行和维护阶段，软件将在运行使用中不断地被维护，根据新提出的需求进行必要而且可能的扩充和删改、更新和升级。 6.2文档编制中的考虑因素文档编制是开发过程的有机组成部分，也是一个不断努力的工作过程。是一个从形成最初轮廓、经反复检查和修改，直至程序和文档正式交付使用的完整过程。其中每一步都要求工作人员做出很大努力。要保证文档编制的质量，要体现每个开发项目的特点，也要注意不要花太多的人力。为此编制中要考虑如下各项因素。 6.2.1文档的读者每一种文档都具有特定的读者。这些读者包括个人或小组、软件开发单位的成员或社会上的公众、从事软件工作的技术人员、管理人员或领导干部。他们期待着使用这些文档的内容来进行工作，例如设计、编写程序、测试、使用、维护或进行计划管理。因此这些文档的作者必须了解自己的读者。这些文档的编写必须注意适应自己的特定读者的水平、特点和要求。 6.2.2重复性本规范中列出的文档编制规范的内容要求中，显然存在某些重复。较明显的重复有两类。引言是每一种文档都要包含的内容，以向读者提供总的梗概.第二类明显的重复是各种文档中的说明部分，如对功能性能的说明；对输入、输出的描述；系统中包含的设备等。这是为了方便每种文档各自的读者，每种文档应该自成体系，尽量避免读一种文档时又不得不去参考另一种文档。当然，在每一种文档里，有关引言、说明等同其他文档相重复的部分，在行文上、在所用的术语上、在详细的程度上，还是应该有一些差别以适应各种文档的不同读者的需要。 6.2.3灵活性鉴于软件开发是具有创造性的脑力劳动，也鉴于不同软件在规模上和复杂程度上差别极大，本规范认为在文档编制工作中应允许一定的灵活性。这种灵活性表现在如下各款。 a.应编制的文档种类尽管本规范认为在一般情况下，一项软件的开发过程中，应产生如上所述的各种文档，然而针对一项具体的软件开发项目，有时不必编制这么多的文档，可以把几种文档合并成一种。一般地说，当项目的规模、复杂性和失败风险增大时，文档编制的范围，管理手续和详细程度将随之增加，反之，则可适当减少。为了恰当地掌握这种灵活性，本规范要求贯彻分工负责的原则，这意味着： 1）一个软件开发单位的领导机构应该根据本单位经营承包的应用软件的专业领域和本单位的管理能力，制定一个对文档编制要求的实施规定，主要是：在不同的条件下，应该形成哪些文档？这些文档的详细程度？该开发单位的每一个项目负责人，必须认真执行这个实施规定。 2）对于一个具体的应用软件项目，项目负责人应根据上述实施规定，确定一个文档编制计划（可以包含在软件开发计划中），其中包括： （1）应该编制哪几种文档，详细程度如何？(2)各个文档的编制负责人和进度要求；(3)审查、批准的负责人和时间进度安排；(4)在开发时间内，各文档的维护、修改和管理的负责人，以及批准手续。每项工作必须落实到人。这个文件编制计划是整个开发计划的重要组成部份。3）有关的设计人员则必须严格执行这个文档编制计划。 b.文档的详细程度从同一份提纲起草的文件的篇幅大小往往不同，可以少到几页，也可以长达几百页。对于这种差别，本规范是允许的。此详细程度取决于任务的规模、复杂性和项目负责人对该软件的开发过程及运行环境所需要的详细程度的判断。 c.文档的扩展当被开发系统的规模非常大〈例如源码超过一百万行〉时，一种文档可以分成几卷编写，可以按其中每一个系统分别编制；也可以按内容划分成多卷，例如：项目开发计划可能包括：质量保证计划，配置管理计划，用户培训计划，安装实施计划； 系统设计说明可分写成：系统设计说明，子系统设计说明；程序设计说明可分写成：程序设计说明，接口设计说明，版本说明； 操作手册可分写成：操作手册，安装实施过程；测试计划可分写成：测试计划，测试设计说明，测试规程，测试用例； 测试分析报告可分写成：综合测试报告，验收测试报告；项目开发总结报告亦可分写成项目开发总结报告和资源环境统计。 d.节的扩张与缩并在有些文档中，可以使用本规范所提供的章、条标题，有存在一系列需要分别讨论的因素。本规范认为，所有的条都可以扩展，可以进一步细分，以适应实际需要。反之如果章条中的有些细节并非必需，也可以根据实际情况缩并。此时章条的编号应相应地变更。 e.程序设计的表现形式本规范对于程序的设计表现形式并未作出规定或限制，可以使用流程图的形式，判定表的形式，也可以使用其他表现形式，如程序设计语言（PDL）、问题分析图（PALb）等。f.文档的表现形式本规范对于文档的表现形式亦未作出规定或限制。可以使用自然语言，也可以使用形式化语言。也可以使用各件图、表。 g.文档的其他种类当本规范中规定的文档种类尚不能满足某些应用部门的特殊需要时，他们可以建立一些特殊的文档种类要求，例如软件质量保证计划、软件配置管理计划等，这些要求可以包含在本单位的文件编制实施规定中。'