软件文档管理指南.ppt
1,软件文档管理指南(GB/T16680-96),2,简介,本标准为那些对软件或基于软件产品的开发负有职责的管理者提供软件文档的管理指南。目的在于协助管理者在他们的机构中产生有效的文档。本标准涉及策略、标准、规程、资源和计划，管理者必须关注这些内容，以便有效地管理软件文档。本标准期望应用于各种类型的软件，从简单的程序到复杂的软件系统。并期望覆盖各种类型的软件文档，作用于软件生存期的各个阶段。,3,简介,不论项目的大小，软件文档管理的原则是一致的。对于小项目，可以不采用本标准中规定的有关细节。管理者可剪裁这些内容以满足他们的特殊需要。本标准是针对文档编制管理而提出的，不涉及软件文档的内容和编排。,4,引用标准,GB 8566-88 计算机软件开发规范 GB 8567-88 计算机软件产品开发文件编制指南 GB/T 11457-1995 软件工程术语,5,定义,文档 document 一种数据媒体和其上所记录的数据。它具有永久性并可以由人或机器阅读。通常仅用于描述人工可读的内容。例如，技术文件、设计文件、版本说明文件。文档（集）/文档编制 documentation 一个或多个相关文档的集合。,6,定义,文档计划 documentation plan 一个描述文档编制工作方法的管理用文档。该计划主要描述要编制什么类型的文档，这些文档的内容是什么，何时编写，由谁编写，如何编写，以及什么是影响期望结果的可用资源和外界因素。,7,定义,文档等级 level of documentation 对所需文档的一个说明，它指出文档的范围、内容、格式及质量，可以根据项目、费用、预期用途、作用范围或其他因素选择文档等级。软件产品 software product 软件开发过程的结果，并推出供用户使用的软件实体。,8,主要内容,软件文档的作用管理者的作用制订文档编制策略制订文档编制标准和指南文档编制计划制订文档规程所需资源,9,软件文档的作用,管理依据质量保证软件维护支持,任务之间联系的凭证 培训与参考 历史档案,10,主要内容,软件文档的作用管理者的作用制订文档编制策略制订文档编制标准和指南文档编制计划制订文档规程所需资源,11,管理者的作用,管理者严格要求软件开发人员和编制组完成文档编制，并且在策略、标准、规程、资源分配和编制计划方面给予支持。,12,管理者对文档工作的责任,管理者要认识到正式或非正式文档都是重要的，还要认识到文档工作必须包括文档计划、编写、修改、形成、分发和维护等各个方面。,13,管理者对文档工作的支持,管理者应为编写文档的人员提供指导和实际鼓励，并使各种资源有效地用于文档开发。,14,管理者的主要职责,建立编制、登记、出版系统文档和软件文档的各种策略把文档计划作为整个开发工作的一个组成部分建立确定文档质量、测试质量和评审质量各种方法的规程为文档的各个方面确定和准备各种标准和指南积极支持文档工作以形成开发中自觉编制文档的团队风气不断检查已建立起来的过程，以保证符合策略和各种规程并遵守有关标准和指南,15,项目管理者在开发前应决定的事项,要求哪些类型的文档提供多少种文档文档包含的内容达到何种级别的质量水平何时产生何种文档如何保存、维护文档以及如何进行通信,如果一个软件合同是有效的，应要求文档满足所接受的标准，并规定所提供的文档类型、每种文档的质量水平以及评审和通过的规程。,16,主要内容,软件文档的作用管理者的作用制订文档编制策略制订文档编制标准和指南文档编制计划制订文档规程所需资源,17,制订文档编制策略,文档策略由上级(资深)管理者准备并支持，对下级开发单位或开发人员提供指导。策略规定主要的方向，不是做什么或如何做的详细说明。一般说来，文档编制策略陈述要明确，并通告到每个人且理解它，进而使策略被他们贯彻实施。,18,支持有效文档策略的基本条件,文档需要覆盖整个软件生存期在项目早期几个阶段就要求有文档，而且在贯穿软件开发过程中必须是可用的和可维护的。在开发完成后，文档应满足软件的使用、维护、增强、转换或传输。文档应是可管理的指导和控制文档的获得和维护，管理者和发行专家应准备文档产品、进度、可靠性、资源，质量保证和评审规程的详细计划大纲。,19,支持有效文档策略的基本条件,文档应适合于它的读者读者可能是管理者、分析员、无计算机经验的专业人员、维护人员、文书人员等。根据任务的执行，他们要求不同的材料表示和不同的详细程度。针对不同的读者，发行专家应负责设计不同类型的文档。文档效应应贯穿到软件的整个开发过程中在软件开发的整个过程中，应充分体现文档的作用和限制，即文档应指导全部开发过程。,20,支持有效文档策略的基本条件,文档标准应被标识和使用应尽可能地采纳现行的标准，若没有合适的现行标准，必要时应研制适用的标准或指南。应规定支持工具工具有助于开发和维护软件产品，包括文档。因此尽可能地使用工具是经济的、可行的。,21,主要内容,软件文档的作用管理者的作用制订文档编制策略制订文档编制标准和指南文档编制计划制订文档规程所需资源,22,制订文档编制标准和指南,在一个机构内部，应采用一些标准和指南：软件生存期模型文档类型和相互关系文档质量这些标准和指南将决定如何实现文档任务，将提供一些准则以评价该机构内所产生的软件文档的完整性、可用性和适合性。尽可能地采用现行的国家和国际标准，若现行的标准不适用，机构应制订自己的标准。,23,1.选择软件生存期模型,现有的一些软件生存期模型，对于不同阶段有不同的词汇。从软件文档的观点来看，采用哪种模型都无关紧要，只要阶段和相应文档是清晰定义的、已计划的，并且对于任何具体软件项目是能遵循的。因此，管理者应选择一个软件生存期模型并保证该模型在他们机构内是适用的。管理者将会发现所进行的阶段和相应任务的定义有助于监控软件项目的进展。相应于特定阶段生成的文档可用作该阶段的评审、通过和完成的检验点，而这种检验应在下一阶段开始前进行。,24,2.规定文档类型和内容,软件文档归入如下三种类别：开发文档描述开发过程本身；产品文档描述开发过程的产物；管理文档记录项目管理的信息。,25,(1)开发文档,开发文档是描述软件开发过程，包括软件需求、软件设计、软件测试、保证软件质量的一类文档，开发文档也包括软件的详细技术描述(程序逻辑、程序间相互关系、数据格式和存储等),26,开发文档的作用,是软件开发过程所有阶段间的通信工具，它记录生成软件需求、设计、编码和测试的详细规定和说明描述开发小组的职责。通过规定软件、主题事项、文档编制、质量保证人员以及包含在开发过程中任何其他事项的角色来定义做什么，如何做和何时做用作检验点而允许管理者评定开发进度。如果开发文档丢失、不完整或过时，管理者将失去跟踪和控制软件项目的一个重要工具；形成了维护人员所要求的基本的软件支持文档，而这些支持文档可作为产品文档的一部分；记录软件开发的历史。,27,基本的开发文档,可行性研究和项目任务书需求规格说明功能规格说明设计规格说明，包括程序和数据规格说明开发计划软件集成和测试计划质量保证计划、标准、进度安全和测试信息,28,(2)产品文档,产品文档规定关于软件产品的使用、维护、增强、转换和传输的信息产品的文档起到如下三种作用为使用运行软件产品的任何人规定培训和参考信息使得那些未参加开发本软件的程序员维护它促进软件产品的市场流通或提高可接受性产品文档用于用户、运行者和软件维护人员,29,产品文档内容,用于管理者的指南和资料它们是用来监督软件的使用的宣传资料用于通告软件产品的可用性并详细说明它的功能、运行环境等一般信息用来对任何有兴趣的人描述软件产品,30,基本的产品文档,培训手册参考手册和用户指南软件支持手册产品手册和信息广告,31,(3)管理文档,这种文档建立在项目管理信息的基础上开发过程每个阶段的进度和进度变更的记录软件变更情况的记录相对于开发的判定记录职责定义从管理的角度规定涉及软件生存的信息,32,相关知识,软件文档分类软件文档与使用者的关系软件生存周期各阶段与各种文档编制的关系文档所回答的问题,33,3.文档的质量等级,仅仅依据规章、传统的做法或合同的要求去制作文档是不够的。管理者还必须确定文档的质量要求以及如何达到和保证质量要求。质量要求的确定取决于可得到的资源、项目的大小和风险，可以对该产品的每个文档的格式及详细程度作出明确的规定。每个文档的质量必须在文档计划期间就有明确的规定。文档的质量可以按文档的形式和列出的要求划分为四级。,34,1级文档,最低限度文档适合开发工作量低于一个人月的开发者自用程序。该文档应包含程序清单、开发记录、测试数据和程序简介,35,2级文档,内部文档可用于在精心研究后被认为似乎没有与其他用户共享资源的专用程序。除1级文档提供的信息外，2级文档还包括程序清单内足够的注释以帮助用户安装和使用程序。,36,3级文档,工作文档适于由同单位若干人联合开发的程序，或可被其他单位使用的程序。,37,4级文档,正式文档适于要正式发行供普遍使用的软件产品。关键性程序或具有重复管理应用性质(如工资计算)的程序需4级文档应遵守GB 8567的有关规定,38,文档质量,质量方面需要考虑的问题即要包含文档的结构，也要包含文档的内容。文档内容可根据正确性、完整性和明确性来判断文档结构由各个组成部分的顺序和总体安排的简单性来测定。要达到这四个质量等级，需要的投入和资源逐级增加，质量保证机构必须处于适当的行政地位以保证达到期望的质量等级。,39,主要内容,软件文档的作用管理者的作用制订文档编制策略制订文档编制标准和指南文档编制计划制订文档规程所需资源,40,文档编制计划,文档计划可以是整个项目计划的一部分或是一个独立的文档。应该编写文档计划并把它分发给全体开发组成员，作为文档重要性的具体依据和管理部门文档工作责任的备忘录对于小的、非正式的项目，文档计划可能只有一页纸；对于较大的项目，文档计划可能是一个综合性的正式文档，这样的文档计划应遵循各项严格的标准及正规的评审和批准过程。,41,文档编制计划,编制计划的工作应及早开始，对计划的评审应贯穿项目的全过程。如同任何别的计划一样，文档计划指出未来的各项活动，当需要修改时必须加以修改。导致对计划作适当修改的常规评审应作为该项目工作的一部分，所有与该计划有关的人员都应得到文档计划,42,文档计划主要内容,列出应编制文档的目录提示编制文档应参考的标准指定文档管理员提供编制文档所需要的条件，落实文档编写人员、所需经费以及编制工具等明确保证文档质量的方法，为确保文档内容的正确性、合理性，应采取一定的措施，如评审、鉴定等绘制进度表，以图表形式列出在软件生存期各阶段应产生的文档、编制人员、编制日期、完成日期、评审日期等。,43,文档计划主要内容,此外，文档计划规定每个文档要达到的质量等级，以及为了达到期望的结果必须考虑哪些外部因素。文档计划还确定该计划和文档的分发，并且明确叙述与文档工作的所有人员的职责。,44,主要内容,软件文档的作用管理者的作用制订文档编制策略制订文档编制标准和指南文档编制计划制订文档规程所需资源,45,制订文档规程,文档编制规程应符合前述文档策略，并适用于整个软件产品生存期内文档的编制和使用这些规程提出关于文档的计划、编制、评审、制作和分发的逻辑顺序。这些规程内含审批、质量保证及若干控制点，概述修改步骤、存储和维护要求以及更新方法。,46,制订文档规程,文档计划制定文档编写 文档编号文档评审 文档签署文档归档与保管 文档维护,47,1.文档计划制定,项目一旦确定，就应制定项目开发计划(包括文档计划)，文档计划的制定遵照前述规定,48,2.文档编写,文档的编写是件非常细致的工作，从最初提出文档编写提纲开始，经过逐步充实、完善，并经反复检查和修改，直至正式交付使用为止。,49,文档编写注意要点,文档编写时间应与软件开发同步，在软件生存期的每一个阶段都应完成相应的文档编写工作按文档计划规定的文档数量和质量要求编写文档按GB 8567或本单位指定标准内容格式编写相应文档文档用纸的格式由各单位按有关标准规定执行每个文档必须装订成册，并加封面和目次归档用的文档还应有扉页，用于各责任者的签署,50,3.文档编号,为便于管理，软件文档应按编号法进行编号编号方法有十进分类法、隶属法等等，各单位可根据本单位实际情况确定一种编号方法不论何种方法，编号应具有唯一性。,51,十进分类法,十进分类编号方法。这种方法就是将产品的设计文件按规定的技术特征（功能、结构、材料、用途、工艺特征），分为10级，每级分为10类，每类分为10型，每型又分为10种。在特征标记前，冠以汉语拼音字母表示企业区分代号，在特征标记后，标上三位数字，表示登记号，最后是文件简号。例:AB 2.022.005 MX AB 2.022.005 MX 企业代号 级类型种 登记顺序号 文件简号,52,隶属编号法,隶属编号,即按隶属关系编号,下级编号应在其所属上级的范围内编号,53,4.文档评审,文档评审十分重要，必须与技术评审结合起来为了提高软件产品的质量，一个有效的方法就是在软件开发的每个阶段，对该阶段所形成的文档进行严格的评审，这样可尽早发现问题，并及时采取措施予以解决，从而确保文档内容的正确性，避免或减少大的返工，同时为进入下一阶段的工作做好组织上和技术上的准备。,54,文档评审,对一些大项目，正规评审通常在开发方法学指导下进行。正规评审应包括文档评审，这是为了保证文档不但正确，而且内容是最新的。如果对文档与开发工作的其他方面同样重要这一点强调不够，各种问题可能随之而来。对所有描述开发工作和产品的文档进行评审是正规评审过程的组成部分。一开始特别重要的是需求规格说明和设计规格说明的评审。,55,(1)需求评审,需求评审进一步确认开发者和设计者已了解用户要求什么，及用户从开发者一方了解某些限制和约束。需求评审(可能需要一次以上)产生一个被认可的需求规格说明。基于对系统要做些什么的共同理解，才能着手详细设计。用户代表必须积极参与开发和需求评审，参与对需求文档的认可。,56,(2)设计评审,通常安排两个主要的设计评审概要设计评审在概要设计评审过程中，主要详细评审每个系统组成部分的基本设计方法和测试计划。系统规格说明应根据概要设计评审的结果加以修改详细设计评审主要评审计算机程序和程序单元测试计划,57,设计评审,设计评审产生的最终文档规定系统和程序将如何设计、开发和测试，以满足一致同意的需求。正规备忘录提供一份有关所有会议的记录。,58,(3)其他评审,其他文档的正规评审也是必需的。产品文档的计划应包括对下述内容的评审和认可：编排方式技术准确度复盖范围的完整性对读者的适合程度图表设计思想及最终图表(也应接受关于技术准确度、适合程度和完整性的单独评审)在语法、标点及其他行文技巧方面的正确性对格式和别的标准的遵守程度,59,评审会步骤,由软件开发单位负责人、用户代表、开发小组成员、科技管理人员和标准化人员等组成评审小组，必要时还可邀请外单位的专家参加；开会前由开发单位负责人确定评审的具体内容，并将评审材料发给评审小组成员，要求做好评审准备由开发单位负责人主持评审会，根据文档编制者对该文档的说明和评审条目，由评审小组成员进行评议、评审，评审结束应作出评审结论，评审小组成员应在评审结论上签字。,60,5.文档签署,软件产品的所有文档，都应按规定进行签署软件文档签署的顺序一般按“编写一审核会签标准化批准”的顺序进行。会签仅在必要时才进行。签署不允许代签。修改单的签署与被修改的文档签署相同。注：会签是撰拟公文的过程中，主办单位主动与有关单位协商并核签的一种办文程序，一般当公文的内容涉及本单位的多个部门或与其它单位有关时，需要进行会签。,61,6.文档归档与保管,软件产品的文档是软件开发过程的真实记录,是重要的信息资源，因此必须实行集中统一管理，使之完善、安全并能有效地利用。,62,(1)文档归档,归档的文档应包括整个软件生存期内所形成的全部文档。文档归档应满足以下条件：归档的文档应是经过鉴定或评审的文档应签署完整、成套、格式统一、字迹工整印制本、打印本以及各种报告应装订成册，并按规定进行编号，签署软件文档应在开发过程每个阶段结束后及时归档,63,(2)文档保管,对一个单位来说，软件文档是极其重要的财富。应在不同的地点建立设施来保存重要文档的副本。这种非现场的保存应储藏所有开发文档和产品文档的后备副本。如果文档是联机开发的，则应把它存储到磁带或磁盘上，以便能够迅速地将这些文档转换成可用的形式。在人为事故或自然灾害情况下，可以使用备用的磁带、磁盘、软盘、清单、系统图等重新构造系统。文档保管包括登记、保存、借阅和修改等四项工作文档保管应按国家和上级主管部门的要求，以及各单位的规章制度规定执行。,64,7.文档维护,软件产品在投入运行后，往往还会有程序错误、文档错误以及适应新的环境和需求而要求增加或修改软件及其相关文档等情况。因此，必须对软件产品及其文档进行维护。,65,文档维护步骤,软件产品完成后，确定软件维护人员在软件的运行过程中，由软件维护人员负责收集、记录从用户或其他途径反馈回来的软件质量信息在分析整理后，填写“软件问题报告”由软件维护人员或项目课题组人员根据“软件问题报告”中提出的要求，填写“软件修改申请报告”根据批准后的“软件修改申请报告”，由该项目的课题组人员或软件维护人员对程序进行修改、测试,66,文档维护步骤(续),测试通过后，由程序修改人员填写“软件修改报告”并修改相应的文档和媒体将“软件修改报告”和修改后的文档送审核、会签、标准化、批准等有关负责人审阅、签署将修改后的文档、媒体和“软件修改报告”送档案管理部门存档软件维护人员汇总并整理修改情况，在此基础上编写“软件维护通报”,67,主要内容,软件文档的作用管理者的作用制订文档编制策略制订文档编制标准和指南文档编制计划制订文档规程所需资源,68,所需资源,为了编制高质量文档，必须得到必要的资源所需的资源包括：人员设备资金,69,(1)人员,技术工作和技术管理主要取决于人。没有任何指南、标准或方法(学)能够代替技术素质高的人。技术写作和文档技术方面的某些培训是必要的，也是有用的。但是，放在首位的仍然是任用既胜任计算机程序开发、又胜任文档工作的人员。,70,(2)设备,某些自动的软件工具已成功地应用于开发文档的编制工作。计算机程序能够提供图表、索引、数据元素表以及子程序和其他程序成分之间的交叉引用。这些可避免令人乏味地重复录入草案材料，并且容许自动地重新打印更新后的文档。用于检查文档的一致性及在需求、设计文档和计算机代码之间提供相关性的计算机技术也已经开发成功。如果自动辅助工具的成本和附加资源相对于整个项目资源来说是合理的，则应加以使用。,71,(3)资金,虽然开发文档的费用很少作为单独的预算项目，且产品文档的费用常常估计过低，但实际上开发文档和产品文档的费用却占开发费用中的很大一部分。支持文档编写人员，他们使用的设备，以及文档的保存、复制、分发和维护都需要资金，评审和更新需要花时间和人力。项目预算和计划表必须反映这些费用。在制定计划过程中应请文档专家和通晓文档工作的人协助制定合理的预算。,72,73,74,75,
