软件文档管理指南ppt课件

1、简介简介 本规范为那些对软件或基于软件产品的开发负有职责的管理者提供软件文档的管理指南。目的在于协助管理者在他们的机构中产生有效的文档。 本规范涉及战略、规范、规程、资源和方案，管理者必需关注这些内容，以便有效地管理软件文档。 本规范期望运用于各种类型的软件，从简单的程序到复杂的软件系统。并期望覆盖各种类型的软件文档，作用于软件生存期的各个阶段。简介简介 不论工程的大小，软件文档管理的原那么是一致的。对于小工程，可以不采用本规范中规定的有关细节。管理者可剪裁这些内容以满足他们的特殊需求。 本规范是针对文档编制管理而提出的，不涉及软件文档的内容和编排。援用规范援用规范 GB 8566-88 计算

2、机软件开发规范 GB 8567-88 计算机软件产品开发文件编制指南 GB/T 11457-2019 软件工程术语 定义定义 文档文档 document 一种数据媒体和其上所记录的数据。它具有一种数据媒体和其上所记录的数据。它具有永久性并可以由人或机器阅读。通常仅用于永久性并可以由人或机器阅读。通常仅用于描画人工可读的内容。例如，技术文件、设描画人工可读的内容。例如，技术文件、设计文件、版本阐明文件。计文件、版本阐明文件。 文档集文档集/ 文档编制文档编制 documentation 一个或多个相关文档的集合。一个或多个相关文档的集合。 定义定义 文档方案文档方案 documentation

3、plan 一个描画文档编制任务方法的管理用文档。一个描画文档编制任务方法的管理用文档。 该方案主要描画要编制什么类型的文档，这该方案主要描画要编制什么类型的文档，这些文档的内容是什么，何时编写，由谁编写，些文档的内容是什么，何时编写，由谁编写，如何编写，以及什么是影响期望结果的可用如何编写，以及什么是影响期望结果的可用资源和外界要素。资源和外界要素。 定义定义 文档等级文档等级 level of documentation 对所需文档的一个阐明，它指出文档的范围、对所需文档的一个阐明，它指出文档的范围、内容、格式及质量，可以根据工程、费用、内容、格式及质量，可以根据工程、费用、预期用途、作用范

4、围或其他要素选择文档等预期用途、作用范围或其他要素选择文档等级。级。 软件产品软件产品 software product 软件开发过程的结果，并推出供用户运用的软件开发过程的结果，并推出供用户运用的软件实体。软件实体。 主要内容主要内容 软件文档的作用软件文档的作用 管理者的作用管理者的作用 制定文档编制战略制定文档编制战略 制定文档编制规范和指南制定文档编制规范和指南 文档编制方案文档编制方案 制定文档规程制定文档规程 所需资源所需资源软件文档的作用软件文档的作用 管理根据 质量保证 软件维护支持 义务之间联络的凭证 培训与参考 历史档案 主要内容主要内容 软件文档的作用软件文档的作用 管理

5、者的作用管理者的作用 制定文档编制战略制定文档编制战略 制定文档编制规范和指南制定文档编制规范和指南 文档编制方案文档编制方案 制定文档规程制定文档规程 所需资源所需资源管理者的作用管理者的作用 管理者严厉要求软件开发人员和编制组完成文档编制，并且在战略、规范、规程、资源分配和编制方案方面给予支持。 管理者对文档任务的责任管理者对文档任务的责任 管理者要认识到正式或非正式文档都是重要的，还要认识到文档任务必需包括文档方案、编写、修正、构成、分发和维护等各个方面。 管理者对文档任务的支持管理者对文档任务的支持 管理者应为编写文档的人员提供指点和实践鼓励，并使各种资源有效地用于文档开发。 管理者的

6、主要职责管理者的主要职责 建立编制、登记、出版系统文档和软件文档的各种战略 把文档方案作为整个开发任务的一个组成部分 建立确定文档质量、测试质量和评审质量各种方法的规程 为文档的各个方面确定和预备各种规范和指南 积极支持文档任务以构成开发中自觉编制文档的团队风气 不断检查已建立起来的过程，以保证符合战略和各种规程并遵守有关规范和指南工程管理者在开发前应决议的事项工程管理者在开发前应决议的事项 要求哪些类型的文档 提供多少种文档 文档包含的内容 到达何种级别的质量程度 何时产生何种文档 如何保管、维护文档以及如何进展通讯 假设一个软件合同是有效的，应要求文档满足所接受的规范，并规定所提供的文档类

7、型、每种文档的质量程度以及评审和经过的规程。 主要内容主要内容 软件文档的作用软件文档的作用 管理者的作用管理者的作用 制定文档编制战略制定文档编制战略 制定文档编制规范和指南制定文档编制规范和指南 文档编制方案文档编制方案 制定文档规程制定文档规程 所需资源所需资源制定文档编制战略制定文档编制战略 文档战略由上级(资深)管理者预备并支持，对下级开发单位或开发人员提供指点。 战略规定主要的方向，不是做什么或如何做的详细阐明。 普通说来，文档编制战略陈说要明确，并通告到每个人且了解它，进而使战略被他们贯彻实施。 支持有效文档战略的根本条件支持有效文档战略的根本条件 文档需求覆盖整个软件生存期 在

8、工程早期几个阶段就要求有文档，而且在贯穿软件开发过程中必需是可用的和可维护的。在开发完成后，文档应满足软件的运用、维护、加强、转换或传输。 文档应是可管理的 指点和控制文档的获得和维护，管理者和发行专家应预备文档产品、进度、可靠性、资源，质量保证和评审规程的详细方案大纲。 支持有效文档战略的根本条件支持有效文档战略的根本条件 文档应适宜于它的读者 读者能够是管理者、分析员、无计算机阅历的专业人员、维护人员、文书人员等。根据义务的执行，他们要求不同的资料表示和不同的详细程度。针对不同的读者，发行专家应担任设计不同类型的文档。 文档效应应贯穿到软件的整个开发过程中 在软件开发的整个过程中，应充分表

9、达文档的作用和限制，即文档应指点全部开发过程。 支持有效文档战略的根本条件支持有效文档战略的根本条件 文档规范应被标识和运用 应尽能够地采用现行的规范，假设没有适宜的现行规范，必要时应研制适用的规范或指南。 应规定支持工具 工具有助于开发和维护软件产品，包括文档。因此尽能够地运用工具是经济的、可行的。 主要内容主要内容 软件文档的作用软件文档的作用 管理者的作用管理者的作用 制定文档编制战略制定文档编制战略 制定文档编制规范和指南制定文档编制规范和指南 文档编制方案文档编制方案 制定文档规程制定文档规程 所需资源所需资源制定文档编制规范和指南制定文档编制规范和指南 在一个机构内部，应采用一些规

10、范和指南： 软件生存期模型 文档类型和相互关系 文档质量 这些规范和指南将决议如何实现文档义务，将提供一些准那么以评价该机构内所产生的软件文档的完好性、可用性和适宜性。 尽能够地采用现行的国家和国际规范，假设现行的规范不适用，机构应制定本人的规范。1. 选择软件生存期模型选择软件生存期模型 现有的一些软件生存期模型，对于不同阶段有不同的词汇。从软件文档的观念来看，采用哪种模型都无关紧要，只需阶段和相应文档是明晰定义的、已方案的，并且对于任何详细软件工程是能遵照的。 因此，管理者应选择一个软件生存期模型并保证该模型在他们机构内是适用的。管理者将会发现所进展的阶段和相应义务的定义有助于监控软件工程

11、的进展。相应于特定阶段生成的文档可用作该阶段的评审、经过和完成的检验点，而这种检验应在下一阶段开场前进展。2. 规定文档类型和内容规定文档类型和内容 软件文档归入如下三种类别： 开发文档描画开发过程本身； 产品文档描画开发过程的产物； 管理文档记录工程管理的信息。(1) 开发文档开发文档 开发文档是描画软件开发过程，包括软件需开发文档是描画软件开发过程，包括软件需求、软件设计、软件测试、保证软件质量的求、软件设计、软件测试、保证软件质量的一类文档，开发文档也包括软件的详细技术一类文档，开发文档也包括软件的详细技术描画描画(程序逻辑、程序间相互关系、数据格式程序逻辑、程序间相互关系、数据格式和存

12、储等和存储等)开发文档的作用开发文档的作用 是软件开发过程一切阶段间的通讯工具，它记录生成软件需求、设计、编码和测试的详细规定和阐明 描画开发小组的职责。经过规定软件、主题事项、文档编制、质量保证人员以及包含在开发过程中任何其他事项的角色来定义做什么，如何做和何时做 用作检验点而允许管理者评定开发进度。假设开发文档丧失、不完好或过时，管理者将失去跟踪和控制软件工程的一个重要工具； 构成了维护人员所要求的根本的软件支持文档，而这些支持文档可作为产品文档的一部分； 记录软件开发的历史。根本的开发文档根本的开发文档 可行性研讨和工程义务书 需求规格阐明 功能规格阐明 设计规格阐明，包括程序和数据规格

13、阐明 开发方案 软件集成和测试方案 质量保证方案、规范、进度 平安和测试信息(2) 产品文档产品文档 产品文档规定关于软件产品的运用、维护、加强、转换和传输的信息 产品的文档起到如下三种作用 为运用运转软件产品的任何人规定培训和参考信息 使得那些未参与开发本软件的程序员维护它 促进软件产品的市场流通或提高可接受性 产品文档用于用户、运转者和软件维护人员产品文档内容产品文档内容 用于管理者的指南和资料 它们是用来监视软件的运用的 宣传资料 用于通告软件产品的可用性并详细阐明它的功能、运转环境等 普通讯息 用来对任何有兴趣的人描画软件产品根本的产品文档根本的产品文档 培训手册 参考手册和用户指南

14、软件支持手册 产品手册和信息广告(3) 管理文档管理文档 这种文档建立在工程管理信息的根底上 开发过程每个阶段的进度和进度变卦的记录 软件变卦情况的记录 相对于开发的断定记录 职责定义 从管理的角度规定涉及软件生存的信息相关知识相关知识 软件文档分类 软件文档与运用者的关系 软件生存周期各阶段与各种文档编制的关系 文档所回答的问题 3. 文档的质量等级文档的质量等级 仅仅根据规章、传统的做法或合同的要求去制造文档是不够的。管理者还必需确定文档的质量要求以及如何到达和保证质量要求。 质量要求确实定取决于可得到的资源、工程的大小和风险，可以对该产品的每个文档的格式及详细程度作出明确的规定。 每个文

15、档的质量必需在文档方案期间就有明确的规定。文档的质量可以按文档的方式和列出的要求划分为四级。 1级文档级文档 最低限制文档最低限制文档 适宜开发任务量低于一个人月的开发者自用适宜开发任务量低于一个人月的开发者自用程序。程序。 该文档应包含程序清单、开发记录、测试数该文档应包含程序清单、开发记录、测试数据和程序简介据和程序简介2级文档级文档 内部文档内部文档 可用于在精心研讨后被以为似乎没有与其他可用于在精心研讨后被以为似乎没有与其他用户共享资源的公用程序。用户共享资源的公用程序。 除除1级文档提供的信息外，级文档提供的信息外，2级文档还包括程级文档还包括程序清单内足够的注释以协助用户安装和运用

16、序清单内足够的注释以协助用户安装和运用程序。程序。 3级文档级文档 任务文档任务文档 适于由同单位假设干人结合开发的程序，或适于由同单位假设干人结合开发的程序，或可被其他单位运用的程序。可被其他单位运用的程序。4级文档级文档 正式文档正式文档 适于要正式发行供普遍运用的软件产品。适于要正式发行供普遍运用的软件产品。 关键性程序或具有反复管理运用性质关键性程序或具有反复管理运用性质(如工资如工资计算计算)的程序需的程序需4级文档级文档 应遵守应遵守GB 8567的有关规定的有关规定文档质量文档质量 质量方面需求思索的问题即要包含文档的构造，也要包含文档的内容。 文档内容可根据正确性、完好性和明确

17、性来判别 文档构造由各个组成部分的顺序和总体安排的简单性来测定。 要到达这四个质量等级，需求的投入和资源逐级添加，质量保证机构必需处于适当的行政位置以保证到达期望的质量等级。 主要内容主要内容 软件文档的作用软件文档的作用 管理者的作用管理者的作用 制定文档编制战略制定文档编制战略 制定文档编制规范和指南制定文档编制规范和指南 文档编制方案文档编制方案 制定文档规程制定文档规程 所需资源所需资源文档编制方案文档编制方案 文档方案可以是整个工程方案的一部分或是一个独立的文档。应该编写文档方案并把它分发给全体开发组成员，作为文档重要性的详细根据和管理部门文档任务责任的备忘录 对于小的、非正式的工程

18、，文档方案能够只需一页纸； 对于较大的工程，文档方案能够是一个综合性的正式文档，这样的文档方案应遵照各项严厉的规范及正规的评审和同意过程。 文档编制方案文档编制方案 编制方案的任务应及早开场，对方案的评审应贯穿工程的全过程。好像任何别的方案一样，文档方案指出未来的各项活动，当需求修正时必需加以修正。导致对方案作适当修正的常规评审应作为该工程任务的一部分，一切与该方案有关的人员都应得到文档方案文档方案主要内容文档方案主要内容 列出应编制文档的目录 提示编制文档应参考的规范 指定文档管理员 提供编制文档所需求的条件，落实文档编写人员、所需经费以及编制工具等 明确保证文档质量的方法，为确保文档内容的

19、正确性、合理性，应采取一定的措施，如评审、鉴定等 绘制进度表，以图表方式列出在软件生存期各阶段应产生的文档、编制人员、编制日期、完成日期、评审日期等。文档方案主要内容文档方案主要内容 此外，文档方案规定每个文档要到达的质量等级，以及为了到达期望的结果必需思索哪些外部要素。 文档方案还确定该方案和文档的分发，并且明确表达与文档任务的一切人员的职责。主要内容主要内容 软件文档的作用软件文档的作用 管理者的作用管理者的作用 制定文档编制战略制定文档编制战略 制定文档编制规范和指南制定文档编制规范和指南 文档编制方案文档编制方案 制定文档规程制定文档规程 所需资源所需资源制定文档规程制定文档规程 文档

20、编制规程应符合前述文档战略，并适用于整个软件产品生存期内文档的编制和运用 这些规程提出关于文档的方案、编制、评审、制造和分发的逻辑顺序。 这些规程内含审批、质量保证及假设干控制点，概述修正步骤、存储和维护要求以及更新方法。制定文档规程制定文档规程 文档方案制定文档方案制定 文档编写文档编写 文档编号文档编号 文档评审文档评审 文档签署文档签署 文档归档与保管文档归档与保管 文档维护文档维护 1. 文档方案制定文档方案制定 工程一旦确定，就应制定工程开发方案(包括文档方案)，文档方案的制定遵照前述规定2. 文档编写文档编写 文档的编写是件非常细致的任务，从最初提出文档编写提纲开场，经过逐渐充实、

21、完善，并经反复检查和修正，直至正式交付运用为止。文档编写留意要点文档编写留意要点 文档编写时间应与软件开发同步，在软件生存期的每一个阶段都应完成相应的文档编写任务 按文档方案规定的文档数量和质量要求编写文档 按GB 8567或本单位指定规范内容格式编写相应文档 文档用纸的格式由各单位按有关规范规定执行 每个文档必需装订成册，并加封面和目次 归档用的文档还应有扉页，用于各责任者的签署3. 文档编号文档编号 为便于管理，软件文档应按编号法进展编号 编号方法有十进分类法、隶属法等等，各单位可根据本单位实践情况确定一种编号方法 不论何种方法，编号应具有独一性。十进分类法十进分类法 十进分类编号方法。这

22、种方法就是将产品的设计文件按规定的技术特征功能、构造、资料、用途、工艺特征，分为10级，每级分为10类，每类分为10型，每型又分为10种。在特征标志前，冠以汉语拼音字母表示企业区分代号，在特征标志后，标上三位数字，表示登记号，最后是文件简号。 例: AB 2.022.005 MX AB 2.022 .005 MX 企业代号 级类型种 登记顺序号 文件简号 隶属编号法隶属编号法 隶属编号,即按隶属关系编号,下级编号应在其所属上级的范围内编号4. 文档评审文档评审 文档评审非常重要，必需与技术评审结合起来 为了提高软件产品的质量，一个有效的方法就是在软件开发的每个阶段，对该阶段所构成的文档进展严厉

23、的评审，这样可尽早发现问题，并及时采取措施予以处理，从而确保文档内容的正确性，防止或减少大的返工，同时为进入下一阶段的任务做好组织上和技术上的预备。 文档评审文档评审 对一些大工程，正规评审通常在开发方法学指点下进展。正规评审应包括文档评审，这是为了保证文档不但正确，而且内容是最新的。假设对文档与开发任务的其他方面同样重要这一点强调不够，各种问题能够随之而来。 对一切描画开发任务和产品的文档进展评审是正规评审过程的组成部分。一开场特别重要的是需求规格阐明和设计规格阐明的评审。(1) 需求评审需求评审 需求评审进一步确认开发者和设计者已了解用户要求什么，及用户从开发者一方了解某些限制和约束。 需

24、求评审(能够需求一次以上)产生一个被认可的需求规格阐明。基于对系统要做些什么的共同了解，才干着手详细设计。用户代表必需积极参与开发和需求评审，参与对需求文档的认可。 (2) 设计评审设计评审 通常安排两个主要的设计评审 概要设计评审 在概要设计评审过程中，主要详细评审每个系统组成部分的根本设计方法和测试方案。系统规格阐明应根据概要设计评审的结果加以修正 详细设计评审 主要评审计算机程序和程序单元测试方案设计评审设计评审 设计评审产生的最终文档规定系统和程序将如何设计、开发和测试，以满足一致赞同的需求。正规备忘录提供一份有关一切会议的记录。(3) 其他评审其他评审 其他文档的正规评审也是必需的。

25、 产品文档的方案应包括对下述内容的评审和认可： 编排方式 技术准确度 复盖范围的完好性 对读者的适宜程度 图表设计思想及最终图表(也应接受关于技术准确度、适宜程度和完好性的单独评审) 在语法、标点及其他行文技巧方面的正确性 对格式和别的规范的遵守程度评审会步骤评审会步骤 由软件开发单位担任人、用户代表、开发小组成员、科技管理人员和规范化人员等组成评审小组，必要时还可约请外单位的专家参与； 开会前由开发单位担任人确定评审的详细内容，并将评审资料发给评审小组成员，要求做好评审预备 由开发单位担任人主持评审会，根据文档编制者对该文档的阐明和评审条目，由评审小组成员进展评议、评审，评审终了应作出评审结

26、论，评审小组成员应在评审结论上签字。5. 文档签署文档签署 软件产品的一切文档，都应按规定进展签署 软件文档签署的顺序普通按“编写一审核会签规范化同意的顺序进展。会签仅在必要时才进展。 签署不允许代签。 修正单的签署与被修正的文档签署一样。 注：会签是撰拟公文的过程中，主办单位自动与有关单位协商并核签的一种办文程序，普通当公文的内容涉及本单位的多个部门或与其它单位有关时，需求进展会签。 6. 文档归档与保管文档归档与保管 软件产品的文档是软件开发过程的真实记录,是重要的信息资源，因此必需实行集中一致管理，使之完善、平安并能有效地利用。(1) 文档归档文档归档 归档的文档应包括整个软件生存期内所

27、构成的全部文档。文档归档应满足以下条件： 归档的文档应是经过鉴定或评审的 文档应签署完好、成套、格式一致、字迹工整 印制本、打印本以及各种报告应装订成册，并按规定进展编号，签署 软件文档应在开发过程每个阶段终了后及时归档(2) 文档保管文档保管 对一个单位来说，软件文档是极其重要的财富。 应在不同的地点建立设备来保管重要文档的副本。这种非现场的保管应贮藏一切开发文档和产品文档的后备副本。假设文档是联机开发的，那么应把它存储到磁带或磁盘上，以便可以迅速地将这些文档转换成可用的方式。在人为事故或自然灾祸情况下，可以运用备用的磁带、磁盘、软盘、清单、系统图等重新构造系统。 文档保管包括登记、保管、借

28、阅和修正等四项任务 文档保管应按国家和上级主管部门的要求，以及各单位的规章制度规定执行。 7. 文档维护文档维护 软件产品在投入运转后，往往还会有程序错误、文档错误以及顺应新的环境和需求而要求添加或修正软件及其相关文档等情况。 因此，必需对软件产品及其文档进展维护。 文档维护步骤文档维护步骤 软件产品完成后，确定软件维护人员 在软件的运转过程中，由软件维护人员担任搜集、记录从用户或其他途径反响回来的软件质量信息 在分析整理后，填写“软件问题报告 由软件维护人员或工程课题组人员根据“软件问题报告中提出的要求，填写“软件修正恳求报告 根据同意后的“软件修正恳求报告，由该工程的课题组人员或软件维护人

29、员对程序进展修正、测试文档维护步骤文档维护步骤 (续续) 测试经过后，由程序修正人员填写 “软件修正报告并修正相应的文档和媒体 将“软件修正报告和修正后的文档送审核、会签、规范化、同意等有关担任人审阅、签署 将修正后的文档、媒体和“软件修正报告送档案管理部门存档 软件维护人员汇总并整理修正情况，在此根底上编写“软件维护通报主要内容主要内容 软件文档的作用软件文档的作用 管理者的作用管理者的作用 制定文档编制战略制定文档编制战略 制定文档编制规范和指南制定文档编制规范和指南 文档编制方案文档编制方案 制定文档规程制定文档规程 所需资源所需资源所需资源所需资源 为了编制高质量文档，必需得到必要的资源 所需的资源包括： 人员 设备 资金(1) 人员人员 技术任务和技术管理主要取决于人。没有任何指南、规范或方法(学)可以替代技术素质高的人。技术写作和文档技术方面的某些培训