1、第二章软件文档及其组成,2.1 软件文档的定义 2.2 软件文档的作用 2.3 软件文档的分类 2.4 软件文档与使用者的关系 2.5 软件生存期各阶段与各种文档编制的关系,第二章软件文档及其组成,2.1 软件文档的定义,2.1.1软件 2.1.2软件文档,2.1.1软件,软件是与计算机系统的操作有关的程序、规程、规则及任何与之有关的文档。GB/T 11457-1995(软件工程术语)程序：“按具体要求产生的、适合计算机处理的指令序列。”程序是软件的重要组成部分，但不是全部。规程：“为解决某一问题而采取的动作的经过的描述”或“每次完成某一任务时要遵循的一组手工的步骤”主要描述在软件生存周期中应
2、如何实施有关政策、规则和标准。例如，测试规程，用于描述进行软件测试时应遵循的测试步骤。规则：指软件开发人员在开发软件时应共同遵守的准则的法规。文档：指一种数据媒体及其记录的数据。它具有永久性并可以由人或机器阅读。通常仅用于描述人工可读的内容。例如，技术文件的设计文件等。,2.1.2软件文档,文档(document)是指某种数据媒体和其中所记录的数据。 文档具有永久性，并可以由人或机器阅读，通常仅用于描述人工可读的东西。 在软件工程中，文档常常用来表示对活动、需求、过程或结果进行描述、定义、规定、报告或认证的任何书面或图示的信息。,2.2 软件文档的作用,2.2.1软件文档的作用 2.2.2对软
3、件文档的基本要求,2.2.1软件文档的作用,文档的桥梁作用,软件文档作为计算机软件的重要组成部分，在软件开发人员、软件管理人员、软件维护人员、用户以及计算机之间起着重要的桥梁作用。,根据软件文档管理指南GB/T16680-1996 软件文档桥梁作用主要体现在以下6方面： 项目管理依据 技术交流的语言 保证项目质量 培训与维护的资料 软件维护支持 记载软件历史的语言,2.2.1软件文档的作用（续）,根据软件文档管理指南GB/T16680-1996 软件文档桥梁作用主要体现在以下6方面： 项目管理依据 项目管理组成 里程碑概念 里程碑在项目管理中的作用,2.2.1软件文档的作用（续）,2.2.1软
4、件文档的作用（续）,项目管理依据 项目管理组成现代项目管理理论认为任何项目都是由两个过程构成的。其一是项目的实现过程，其二是项目的管理过程，其中项目的实现过程是指人们为创造项目的产生物而开展的各种活动所构成过程。项目的实现过程一般用项目的生命周期来说明描述它们的活动和内容。,2.2.1软件文档的作用（续）,项目管理依据 里程碑概念里程碑是项目中完成阶段性工作的标志。不同类型的项目里程碑也不同。例如，在软件开发项目中，可以将需求的最终确认、产品移交等关键任务作为项目的里程碑。每个项目阶段都以一个或一个以上的工作成果的完成为标志。这种工作成果是有形的，可鉴定的。例如，一份需求规格说明书、一份详细的
5、设计图等。里程碑的建立必须连带交付物，而这种交付物必须让客户确认。当客户确认交付物后，也是客户确定项目团队已经在系统开发的过程中到达某一个指定的阶段，完成某一部分的工作。在软件开发过程的产生各种软件文档就是里程碑的重要组成部分。,2.2.1软件文档的作用（续）,项目管理依据 里程碑在项目管理中的作用 对于一些复杂的项目，需要逐步逼近目标，里程碑产出的中间“交付物”是每一步逼近的结果。也是控制的对象。如果没有里程碑，中间想知道“项目做得怎样了”是很困难的 可以降低项目风险。通过早期评审可以提前发现需求和设计中的问题，降低后期修改和返工的可能性。另外，还可根据每个阶段的产出结果分期确认收，避免血本
6、无归。 一般人在工作时都有“前松后紧”的习惯，而里程碑强制规定在某个阶段做什么，从而可以合理分配工作，细化管理。,2.2.1软件文档的作用（续）,2. 技术交流的语言没有软件文档，每个软件开发人员只能自扫“门前雪”，别人对你的工作很难插手或提供帮助。软件文档可以改善软件开发从员之间的“爱莫能助”的局面，增强开发人员之间的通讯交流 。因此，软件文档可以看成是软件技术人员进行“技术交流的语言”。,2.2.1软件文档的作用（续）,3. 保证项目质量软件文档是进行项目质量审查和评价的重要依据，也是保证软件项目质量的重要技术文档。,2.2.1软件文档的作用(续),4. 培训与维护的资料软件文档提供对软件
7、的有关运行、维护和培训的信息，便于管理人员、开发人员、操作人员和用户了解系统如何工作，以及如何使用系统。 5. 软件维护支持维护人员需要软件系统的详细说明以帮助他们熟悉系统，找出并修正错误，改进系统以适应用户需求的变化或适应系统环境的变化。 6. 记载软件历史的语言软件文档作为“记载软件历史的语言”，记录了开发过程中的技术信息，便于协调以后的软件开发、使用和修改。,从某种意义上来说，文档是软件开发规范的体现和指南。 按规范要求生成一整套文档的过程，就是按照软件开发规范完成一个软件开发的过程。 所以，在使用工程化的原理和方法来指导软件的开发和维护时，应当充分注意软件文档的编制和管理。案例1：ht
8、tp:/ 案例2：浅谈计算机文档的重要性,2.3 文档的分类,2.3.1按软件文档从形式进行划分 2.3.2按照文档产生和使用的范围进行划分,2.3 文档的分类,2.3.1按软件文档从形式进行划分 软件文档从形式上来看，大致可分为两类： （1）一类是开发过程中填写的各种图表，称之为工作表格； （2）一类是应编制的技术资料或技术管理资料，称之为文档或文件。 软件文档的编制，可以用自然语言，特别设计的形式语言，介于两者之间的半形式语言(结构化语言)，各类图形表示、表格来编制文档。如程序流程图、判定表、程序描述语言(PDL)、或问题分析图(PAD)等。 文档可以书写编制，也可以利用计算机支持系统辅助
9、编制，但必须方便阅读。,2.3.2按照文档产生和使用的范围进行划分 软件文档可分为开发文档、用户文档、管理文档三类：,2.3 文档的分类,1. 开发文档,开发文档作用 开发文档分类,开发文档作用开发文档是描述软件开发过程包括：软件需求、软件设计、软件测试、保证软件质量的一类文档。开发文档也包括软件的详细技术，描述程序逻辑程序间相互关系数据格式和存储等。开发文档起到如下五种作用. 它们是软件开发过程中包含的所有阶段之间的通信工具 它们描述开发小组的职责，通过规定软件主要事项、文档编制质量，保证人员以及包含在开发过程中任何其他事项的角色，来定义做什么如何做和何时做。 它们用作检验点而允许管理者评定
10、开发进度。如果开发文档丢失不完整或过时，管理者将失去跟踪和控制软件项目的一个重要工具。 它们形成了维护人员所要求的基本的软件支持文档，而这些支持文档可作为产品文档的一部分。 它们记录软件开发的历史,1. 开发文档,1. 开发文档,开发文档分类 可行性研究报告 项目开发计划 软件需求说明书 数据库设计说明书 概要设计说明书 详细设计设计书,1. 开发文档,可行性研究报告 说明该软件项目的实现在技术上、经济上和社会因素上的可行性;评述为合理地达到开发目标可供选择的各种可能的实现方案;说明并论证所选定实施方案的理由。,开发文档分类,项目开发计划为软件项目实施方案制定出的具体计划。它包括各部分工作的负
11、责人员开发的进度开发经费的概算所需的硬件和软件资源等项目开发计划应提供给管理部门，并作为开发阶段评审的基础。,1. 开发文档,开发文档分类,开发文档分类 软件需求说明书对目标软件的功能、性能、用户界面及运行环境等作出详细的说明。它是用户与开发人员双方对软件需求取得共同理解基础上达成的协议，也是实施开发工作的基础。,1. 开发文档,开发文档分类数据库设计说明书数据库设计说明书的编制目的是对于设计中的数据库的所有标识、逻辑结构和物理结构作出具体的设计规定。,1. 开发文档,开发文档分类 概要设计说明书该说明书是概要设计工作阶段的成果。它应当说明系统的功能分配模块划分程序的总体结构输入输出及接口设计
12、运行设计数据结构设计出错处理设计等为详细设计奠定基础。,1. 开发文档,详细设计说明书着重描述每一个模块是如何实现的，包括实现算法、逻辑流程等。,1. 开发文档,2. 产品文档,产品文档又称用户文档 ，用于规定关于软件产品的使用维护增强转换和传输的信息，用户文档主要负责对软件产品的使用、维护等信息进行描述产品文档作用 产品文档适用的对象 产品文档内容 基本产品文档,2. 产品文档（续）,产品文档作用 （1）为使用和运行软件产品的客户提供培训和参考信息； （2）使得那些未参加开发本软件的程序员维护它； （3）促进软件产品的市场流通或提高可接受性。,2. 产品文档（续）,产品文档适用的对象产品文档
13、用于下列类型的读者： 用户：他们利用软件输入数据检索信息和解决问题 运行者：他们在计算机系统上运行软件 维护人员：他们维护增强或变更软件,2. 产品文档（续）,产品文档内容 用于管理者的指南和资料 宣传资料 一般信息 基本的产品文档：包括培训手册、参考手册和用户指南、软件支持手册、产品手册和信息广告,2. 产品文档（续）,基本产品文档 基本的用户文档包括培训手册、参考手册和用户指南、软件支持手册、产品手册和信息广告。GB/T16680-1996 1用户手册详细描述软件的功能、性能和用户界面，使用户了解如何使用该软件。 2操作手册为操作人员提供软件各种运行情况的有关知识，特别是操作方法细节。 3
14、数据要求说明书给出数据逻辑描述和数据采集的各项要求, 为生成和维护系统的数据文件做好准备 4维护修改建议 软件产品投入运行以后，发现了需对其进 行修正、更改等问题，应将存在的问题、修改的考虑以及修改的影 响估计作详细的描述，写成维护修改建议，提交审批 。,3. 管理文档,管理文档作用 管理文档类型,管理文档主要有以下作用： （1）开发过程的每个阶段的进度和进度变更的记录； （2）软件变更情况的记录； （3）相对于开发的判定记录； （4）职责定义。,管理文档作用,3. 管理文档,3. 管理文档 管理文档类型,1项目开发计划为软件项目实施方案制定出的具体计划。它包括各部分工作的负责人员开发的进度开
15、发经费的概算所需的硬件和软件资源等项目开发计划应提供给管理部门，并作为开发阶段评审的基础。,2 模块开发卷宗模块开发卷宗是在模块开发过程中逐步编写出来的，每完成一个模块或一组密切相关的模块的复审时编写一份，应该把所有的模块开发卷宗汇集在一起。编写的目的是记录和汇总低层次开发的进度和结果，以便于对整个模块开发工作的管理和复审，并为将来的维护提供非常有用的技术信息。,管理文档类型,3. 管理文档,3开发进度月报该月报是软件人员按月向管理部门提交的项目进展情况的报告。报告应包括进度计划与实际执行情况的比较、阶段成果、遇到的问题和解决的办法以及下个月的打算等。 4测试计划针对组装测试和确认测试，需要为
16、组织测试制定计划。计划应包括测试的内容进度安排条件人员测试用例的选取原则测试结果允许的偏差范围等,3. 管理文档,管理文档类型,5测试分析报告测试工作完成后，应提交测试计划执行情况的说明。对测试结果加以分析，并提出测试的结论性意见。 6项目开发总结报告软件项目开发完成之后，应当与项目实施计划对照，总结实际执行的情况，如进度、成果、资源利用、成本和投入的人力。还需对开发工作作出评价，总结经验和教训。,3. 管理文档,管理文档类型,2.4 软件文档与使用者的关系,对于使用文件的人员而言，他们所关心的文件的种类，随他们所承担的工作而异。 有四种类型人员：管理人员，开发人员，维护人员，用户。 不同类型
17、的人员涉及的文档 管理人员： 可行性研究报告，项目开发计划，模块开发卷宗，开发进度月报，项目开发总结报告；,2.4 软件文档与使用者的关系,开发人员：可行性研究报告，项目开发计划，软件需求说明书，数据要求说明书， 概要设计说明书，详细设计说明书，数据库设计说明书，测试计划，测试分析报告；,2.4 软件文档与使用者的关系,维护人员：设计说明书，测试分析报告，模块开发卷宗；用户：用户手册， 操作手册。 尽管本指南提出了在软件开发中文件编制的要求，但并不意味着这些文件都必须交给用户。一项软件的用户应该得到的文件的种类由供应者与用户之间签订的合同规定。,2.4 软件文档与使用者的关系,2.5 软件生存
18、期各阶段与各种文档编制的关系,按GB/8567-88开 发 文 件 编 制 指 南 认为在一项计算机软件的开发过程中，一般地说，应该产生十四种文件 。（见教材P21） 按GB16680-1996软件文档管理指南认为将产生41种文档 生存周期 软件生存期各阶段所涉及的文档（GB 8567-88） GB16680-1996规定的软件文档编制时间 GB16680-1996与GB8567-88对14种文档编制时间不同之处,2.5 软件生存期各阶段与各种文档编制的关系,生存周期 一项计算机软件，从出现一个构思之日起，经过这项软件开发成功投入使用，直到最后决定停止使 用，并被另一项软件代替之时止，被认为是
19、该软件的一个生存周期 。 按瀑布模型软件生存周期可以分成以下六个阶段： 可行性研究与计划阶段（制定计划阶段） 需求分析阶段设计阶段 （软件设计）实现阶段 （程序编写）测试阶段运行与维护阶段,2.5 软件生存期各阶段与各种文档编制的关系,软件生存期各阶段所涉及的文档（ GB 8567-88 ） 可行性研究与计划阶段 需求分析阶段设计阶段 实现阶段 测试阶段运行与维护阶段,2.5 软件生存期各阶段与各种文档编制的关系,可行性研究与计划阶段 目的与任务 确定要开发软件系统的总目标，给出它的功能、性能、可靠性及接口等方面的要求；由系统分析员和用户合作，研究完成该项软件任务的可行性，探讨解决问题的可能方
20、案，并对可利用的资料、成本、可取得的效益、开发的进度做出估计，制定出完成开发任务的实施计划，连同可行性研究报告，提交管理部门审查。 要编制的文档 （1）开始并完成可行性研究报告（2）开始编制项目开发计划（3）开始编制开发进度月报,2.5 软件生存期各阶段与各种文档编制的关系,需求分析阶段 目的与任务 对待开发软件提出的需求进行分析并给出详细的定义。系统分析人员和用户共同讨论决定：哪些需求是可以满足的，并对其加以确切的描述。然后编写出软件需求说明书或系统功能说明书，及初步的系统用户手册，提交管理机构评审。 要编制的文档 （1）开始并完成软件需求说明书（2）开始编制用户手册 （3）开始编制测试计划
21、（4）开始并完成数据要求说明书 （5）完成项目开发计划（6）继续编制开发进度月报,软件生存期各阶段所涉及的文档（ GB 8567-88 ）设计阶段 目的与任务 软件设计是软件工程的技术核心。软件设计阶段需确定软件的结构、模块的划分、功能的分配以及处理流程。在被设计系统比较复杂的情况下，设计阶段应分解成概要设计阶段和详细设计阶段两个步骤。 要编制的文档 （1）开始并完成概要设计说明书 （2）开始并完成详细设计说明书 （3）完成测试计划 （4）继续编制开发进度月报 （5）继续编制用户手册 （6）开始编制操作手册 （7）开始并完成数据库设计说明书,2.5 软件生存期各阶段与各种文档编制的关系,2.5
22、 软件生存期各阶段与各种文档编制的关系,软件生存期各阶段所涉及的文档（ GB 8567-88 ）实现阶段 目的与任务 把软件设计转换成计算机可以接受的程序代码，即写成以某一种特定程序设计语言表示的“源程序清单” 写出的程序应当是结构良好、清晰易读的，且与设计相一致 要编制的文档 （1）开始编制模块开发卷宗（2）继续编制用户手册（3）继续编制操作手册（4）继续编制开发进度月报,2.5 软件生存期各阶段与各种文档编制的关系,软件生存期各阶段所涉及的文档（ GB 8567-88 ） 测试阶段 目的与任务测试是保证软件质量的重要手段，其主要方式是在设计测试用例的基础上检验软件的各个组成部分，然后依次执
23、行三类测试。 单元测试，查找各模块在功能和结构上存在的问题并加以纠正 组装测试，将已测试过的模块按一定顺序组装起来 按规定的各项需求，逐项进行有效性测试，决定已开发的软件是否合格，能否交付用户使用,2.5 软件生存期各阶段与各种文档编制的关系,软件生存期各阶段所涉及的文档（ GB 8567-88 ） 测试阶段 要编制的文档 （1）完成模块开发卷宗 （在实现阶段开始） （2）开始并完成测试分析报告(需求分析阶段就开始编制测试计划到设计阶段完成) （3）继续编制开发进度月报 （4）开始编制项目开发总结报告,2.5 软件生存期各阶段与各种文档编制的关系,运行与维护阶段 目的与任务 已交付的软件投入正
24、式使用，便进入运行阶段。这一分阶段可能持续若干年甚至几十年。软件在运行中可能由于多方面的原因，需要对它进行修改。其原因可能有：运行中发现了软件中的错误需要修正（改正性维护）；为了适应变化了的软件工作环境，需做适当变更（适应性维护）；为了增强软件的功能需做变更完善性维护 。 要编制的文档 根据新提出的需求进行必要而且可能的扩充和删改,各阶段需要编写的软件文档与软件生存周期的关系,文档最终要向软件管理部门或向用户回答下列问题(6W):(1)哪些需求要被满足（What）； (2)软件在什么环境中实现，所需信息从哪里来（Where）； (3)开发时间如何安排（When）； (4)开发(或维护)工作打算
25、由谁来做（Who）； (5)需求应如何实现（How）； (6)为什么要进行这些软件开发或维护修改工作（Why）。,文档要回答的问题,为使软件文档能 (1)起到多种桥梁的作用； (2)有助于程序员编制程序； (3)有助于管理人员监督和管理软件的开发； (4)有助于用户了解软件的工作和应做的操作； (5)有助于维护人员进行有效的修改和扩充。文档的编制必须保证一定的质量！,GB16680-1996规定的软件文档编制时间,可行性研究与计划阶段 要编制的文档 （1）下达任务书 （2）开始并完成可行性研究报告 （3）开始编制项目开发计划 （4）开始编制软件分析报告 （5）开始编制开发进度月报 （6）阶段评
26、审结果：可行性评审报告,GB16680-1996规定的软件文档编制时间,需求分析 要编制的文档 （1）开始并完成软件需求说明书 （2）开始编制用户手册 （3）开始编制测试计划 （4）开始并完成数据要求说明书 （5）完成项目开发计划 （6）继续编制开发进度月报,设计阶段 要编制的文档 （1）开始并完成概要设计说明书 （2）开始并完成详细设计说明书 （3）完成测试计划 （4）继续编制开发进度月报 （5）继续编制用户手册 （6）继续编制操作手册 （7）开始并完成数据库设计说明书 （8）开始编制模块开发卷宗（GB/T16680-1996）,GB16680-1996规定的软件文档编制时间,GB16680
27、-1996规定的软件文档编制时间,实现阶段 要编制的文档 （1）开始编制模块开发卷宗 （2）继续编制用户手册 （3）继续编制操作手册 （4）继续编制开发进度月报,GB16680-1996规定的软件文档编制时间,测试阶段 要编制的文档 （1）完成模块开发卷宗 （2）开始并完成测试分析报告 （3）继续编制用户手册 （GB/T 16680-1996） （4）继续编制操作手册（GB/T 16680-1996） （5）继续编制开发进度月报 （6）开始编制项目开发总结报告,GB16680-1996规定的软件文档编制时间,运行与维护阶段 要编制的文档 根据新提出的需求进行必要而且可能的扩充和删改,GB166
28、80-1996规定的软件文档编制时间,GB16680-1996规定的软件文档编制时间,GB16680-1996规定的软件文档编制时间,GB16680-1996规定的软件文档编制时间,GB16680-1996与GB8567-88对14种文档编制时间不同之处,（1）测试计划： 在GB8657-88中规定在文字中规定：在设计阶段开始编制并在实现阶段完成，但在表中规定：从需求分析开始到软件设计结束 GB16680-1996中规定：从需求分析开始到软件结束 （2）模块开发卷宗 GB8657-88：编码与实现、集成与测试阶段中编制 GB16680-1996：详细设计、编码与实现、集成与测试阶段中编制 （3）用户手册 GB8657-88：在需求分析、软件设计、编码与实现阶段中编制 GB16680-1996：需求分析、软件设计、编码与实现、测试与试运行 （4）操作手册 GB8657-88：软件设计、编码与实现 GB16680-1996：中规定从概要设计到试运行,
