软件文档.docx

1、软件文档软件文档文档的作用和分类软件文档(document)也称文件，通常指的是一些记录的数据 和数据媒体，它具有固定不变的形式，可被人和计算机阅读。它和 计算机程序共同构成了能完成特定功能的计算机软件(有人把源 程序也当作文档的一部分)。我们知道，硬件产品和产品资料在整 个生产过程中都是有形可见的，软件生产则有很大不同，文档本 身就是软件产品。没有文档的软件，不成其为软件，更谈不到软件 产品。软件文档的编制(documentation)在软件开发工作中占有突 出的地位和相当的工作量。高效率、高质量地开发、分发、管理和维 护文档对于转让、变更、修正、扩充和使用文档，对于充分发挥软 件产品的效益

2、有着重要意义。 然而，在实际工作中，文档在编制和使用中存在着许多问 题，有待于解决。软件开发人员中较普遍地存在着对编制文档不感 兴趣的现象。从用户方面看，他们又常常抱怨：文档售价太高、文 档不够完整、文档编写得不好、文档已经陈旧或是文档太多，难于 使用等等。究竟应该怎样要求它，文档应该写哪些，说明什么问 题，起什么作用?这里将给出简要的介绍。 图 文档桥梁作用文档在软件开发人员、软件管理人员、维护人员、用户以及计 算机之间的多种桥梁作用可从图92中看出。软件开发人员在各 个阶段中以文档作为前阶段工作成果的体现和后阶段工作的依 据，这个作用是显而易见的。软件开发过程中软件开发人员需制定 一些工作

3、计划或工作报告，这些计划和报告都要提供给管理人员， 并得到必要的支持。管理人员则可通过这些文档了解软件开发项 目安排、进度、资源使用和成果等。软件开发人员需为用户了解软 件的使用、操作和维护提供详细的资料，我们称此为用户文档。以 上三种文档构成了软件文档的主要部分。我们把这三种文档所包 括的内容列在图6中。其中列举了十三个文档，这里对它们作 一些简要说明： 可行性研究报告：说明该软件开发项目的实现在技术上、经 济上和社会因素上的可行性，评述为了合理地达到开发目标可供 选择的各种可能实施的方案，说明并论证所选定实施方案的理 由。 项目开发计划：为软件项目实施方案制定出具体计划，应 该包括各部分工

4、作的负责人员、开发的进度、开发经费的预算、所 需的硬件及软件资源等。项目开发计划应提供给管理部门，并作 为开发阶段评审的参考。 软件需求说明书：也称软件规格说明书，其中对所开发软 件的功能、性能、用户界面及运行环境等作出详细的说明。它是用 户与开发人员双方对软件需求取得共同理解基础上达成的协议， 也是实施开发工作的基础。 数据要求说明书：该说明书应给出数据逻辑描述和数据采 集的各项要求，为生成和维护 系统数据文卷作好准备。 概要设计说明书：该说 明书是概要设计阶段的工作 成果，它应说明功能分配、模 块划分、程序的总体结构、输 入输出以及接口设计、运行设 计、数据结构设计和出错处理 设计等，为详

5、细设计奠定基 础。 详细设计说明书：着重 描述每一模块是怎样实现的， 包括实现算法、逻辑流程等。 用户手册：本手册详细 描述软件的功能、性能和用户 界面，使用户了解如何使用该软件。文档 用户文档 用户手册操作手册维护修改建议软件需求（规格）说明书开发文档 软件需求（规格）说明书数据要求说明书概要设计说明书详细设计说明书可行性研究报告项目开发计划管理文档 项目开发计划测试计划测试报告开发进度月报开发总结报告图 三种文档操作手册：本手册为操作人员提供该软件各种运行情况的 有关知识，特别是操作方法的具体细节。 测试计划：为做好组装测试和确认测试，需为如何组织测试 制定实施计划。计划应包括测试的内容、

6、进度、条件、人员、测试用 例的选取原则、测试结果允许的偏差范围等。 测试分析报告：测试工作完成以后，应提交测试计划执行 情况的说明。对测试结果加以分析，并提出测试的结论意见。 开发进度月报：该月报系软件人员按月向管理部门提交的 项目进展情况报告。报告应包括进度计划与实际执行情况的比较、 阶段成果、遇到的问题和解决的办法以及下个月的打算等。 项目开发总结报告：软件项目开发完成以后，应与项目实 施计划对照，总结实际执行的情况，如进度、成果、资源利用、成本 和投入的人力。此外还需对开发工作作出评价，总结出经验和教 训。 维护修改建议，软件产品投入运行以后，发现了需对其进 行修正、更改等问题，应将存在

7、的问题、修改的考虑以及修改的影 响估计作详细的描述，写成维护修改建议，提交审批。 以上这些文档是在软件生存期中，随着各阶段工作的开展适 时编制。其中有的仅反映一个阶段的工作，有的则需跨越多个阶 段。表5给出了各个文档应在软件生存期中哪个阶段编写。这 些文档最终要向软件管理部门，或是向用户回答以下的问题： 表9.2 软件生存期各阶段编制的文档 阶段文档 可行性药酒与计划需求分析设计代码编写测试运行与维护可行性研究报告 项目开发计划 软件需求说明 数据要求说明 概要设计说明 星系设计说明 测试计划 用户手册 操作手册 测试分析报告 开发进度月报 项目开发总结 维护修改建议 哪些需求要被满足，即回答

8、“做什么?” 所开发的软件在什么环境中实现以及所需信息从哪里来， 即回答“从何处?” 某些开发工作的时间如何安排，即回答“何时干?” 某些开发(或维护)工作打算由“谁来干?” 某些需求是怎么实现的? 为什么要进行那些软件开发或维护修改工作? 上述十三个文档都在一定程度上回答了这六个方面的问题。这可从表中看到。表 文档所回答的问题所提问题文档 什么 何处 何时 谁 如何 为何 可行性研究报告 项目开发计划 软件需求说明 数据要求说明 概要设计说明 详细设计说明 测试计划 用户手册 操作手册 测试分析报告 开发进度月报 项目开发总结 维护修改建议 至此，我们对文档的作用有了进一步的理解。每一个文档

9、的任 务也是明确的，任何一个文档都此是多余的。 文档的管理和维护 在整个软件生存期中，各种文档作为半成品或是最终成品， 会不断地生成、修改或补充。为了最终得到高质量的产品，达到上 节提出的质量要求，必须加强对文档的管理。以下几个方面是应注意做到的： 软件开发小组应设一位文档保管人员，负责集中保管本 项目已有文档的两套主文本。两套文本内容完全一致。其中的一套可按一定手续，办理借阅。 软件开发小组的成员可根据工作需要在自己手中保存一些个人文档。这些一般都应是主文本的复制件，并注意和主文本保持一致，在作必要的修改时，也应先修改主文本。 开发人员个人只保存着主文本中与他工作相关的部分文档。 在新文档取

10、代了旧文档时，管理人员应及时注销旧文档。 在文档内容有更动时，管理人员应随时修订主文本，使其及时反映更新了的内容。 项目开发结束时，文档管理人员应收回开发人员的个人文档。发现个人文档与主文本有差别时，应立即着手解决。这常常是未及时修订主文本造成的。 在软件开发过程中，可能发现需要修改已完成的文档，特别是规模较大的项目，主文本的修改必须特别谨慎。修改以前要充分估计修改可能带来的影响，并且要按照：提议、评议、审核、批准和实施等步骤加以严格的控制。文档编制的质量要求 为了使软件文档能起到前节所提到的多种桥梁作用，使它有 助于程序员编制程序，有助于管理人员监督和管理软件开发，有助 于用户了解软件的工作

11、和应做的操作，有助于维护人员进行有效 的修改和扩充，文档的编制必须保证一定的质量。质量差的软件文 档不仅使读者难于理解，给使用者造成许多不便，而且会削弱对 软件的管理(管理人员难以确认和评价开发工作的进展)，增高软 件的成本(一些工作可能被迫返工)，甚至造成更加有害的后果(如误操作等)。 造成软件文档质量不高的原因可能是： 缺乏实践经验，缺乏评价文档质量的标准。 不重视文档编写工作或是对文档编写工作的安排不恰当。 最常见到的情况是，软件开发过程中不能按表5给出的进度， 分阶段及时完成文档的编制工作，而是在开发工作接近完成时集 中人力和时间专门编写文档。另一方面，和程序工作相比，许多 人对编制文

12、档不感兴趣。于是在程序工作完成以后，不得不应付 一下，把要求提供的文档赶写出来。这样的做法不可能得到高质 量的文档。实际上，要得到真正高质量的文档并不容易，除去应在 认识上对文档工作给予足够的重视外，常常需要经过编写初稿， 听取意见进行修改，甚至要经过重新改写的过程。 高质量的文档应当体现在以下一些方面： 针对性；文档编制以前应分清读者对象，按不同的类型、不 同层次的读者，决定怎样适应他们的需要。例如，管理文档主要是 面向管理人员的，用户文档主要是面向用户的，这两类文档不应 像开发文档(面向软件开发人员)那样过多地使用软件的专业术语。 精确性：文档的行文应当十分确切，不能出现多义性的描 述。同

13、一课题若干文档内容应该协调一致，应是没矛盾的。 清晰性：文档编写应力求简明，如有可能，配以适当的图 表，以增强其清晰性。 完整性：任何一个文档都应当是完整的、独立的，它应自成 体系。例如，前言部分应作一般性介绍，正文给出中心内容，必要 时还有附录，列出参考资料等。同一课题的几个文档之间可能有些 部分相同，这些重复是必要的。例如，同一项目的用户手册和操作 手册中关于本项目功能、性能、实现环境等方面的描述是没有差别 的。特别要避免在文档中出现转引其它文档内容的情况。比如，一 些段落并未具体描述，而用“见文档节”的方式，这将给 读者带来许多不便。 灵活性：各个不同的软件项目，其规模和复杂程度有着许

14、多实际差别，不能一律看待。图6所列文档是针对中等规模 的软件而言的。对于较小的或比较简单的项目，可做适当调整或合 并。比如，可将用户手册和操作手册合并成用户操作手册；软件需 求说明书可包括对数据的要求，从而去掉数据要求说明书；概要设 计说明书与详细设计说明书合并成软件设计说明书等。 可追溯性；由于各开发阶段编制的文档与各阶段完成的工 作有着紧密的关系，前后两个阶段生成的文档，随着开发工作的逐 步扩展，具有一定的继承关系。在一个项目各开发阶段之间提供的 文档必定存在着可追溯的关系。例如，某一项软件需求，必定在设 计说明书，测试计划以至用户手册中有所体现。必要时应能做到 跟踪追查。程序文档合一与动

15、态文档很多企业已经建立了许多庞大的计算机管理系统，而且将不断地推出新的系统。满足经营的需求须不断维护、改造计算机系统，但同时又要不影响现行生产，所以必须建立一整套机制来评价、控制和完成对系统的维护。在软件维护过程中，提出程序与文档合一的概念在软件开发的同时建立动态文档。 程序与文档合一概念的提出 一、目前软件的状况 程序与文档的形式分离，不仅是用各自独立的形式存放，而且使用不同的工具在不同的时间里书写和检索。维护程序时不能方便地得到文档的帮助，不能同步修改文档。 程序与文档的内容分离，由于程序与文档采用不同的描述，既有计算机语言也有自然语言。维护过程中不能及时、一致地更新文档或程序，使文档不能

16、准确地描述程序而几乎成为废纸甚至带来负面价值。 软件开发与维护的分离，绝大多数软件在设计、开发时不太考虑以后可能的修改，加大了软件维护的难度，而且使维护容易引入新的错误。 这些分离也表现在设计、开发的不同阶段的文档之间的不相容性，例如：需求分析说明书是纸上的东西，在概要设计阶段不能很好地继承、利用需求分析说明书，设计、编制概要设计时必须从零开始，需要重新分析、理解需求分析，这种思维上的脱节，不仅延缓开发进度、加重设计人员的负担，而且由于理解上的不同导致不同阶段描述的对象有许多不相容情况。这些分离使得文档在系统的设计、开发、维护中的作用下降，这也是很多软件人员不愿意编写文档的主要原因。 二、程序

17、与文档合一的概念提出 怎样才是好的文档系统呢？应当具备以下属性： 1. 能够准确地描述软件、并且简单易懂； 2. 能够迅速错误定位、影响分析、修正设计； 3. 能够提高软件维护质量； 4. 能够方便程序修改时理解程序。 为此提出了程序与文档合一的概念。这概念使软件成为真正意义上的软件：程序+文档，程序就是文档，文档集成在程序中。它要求在选择开发环境时不仅要考虑环境对设计、开发的完美支持，而且要考虑对维护、文档的支持；它要求软件人员在设计、开发过程中要考虑维护问题、文档问题；它要求程序与文档存储在同一位置、同一系统中；它要求使用相同工具进行程序与文档的书写、检索；它要求在编写和维护程序的同时形成

18、文档，在书写文档时编写、维护程序。程序与文档合一的概念不仅存在于系统的设计、开发阶段而且存在于系统的维护阶段，它贯穿软件的生命周期。 动态文档系统是建立在程序与文档合一的概念基础上的、文档与程序一致的、简单易懂的联机文档系统。它包括构件说明与数据描述、对构件与构件之间、构件与数据之间的关系进行的描述。动态文档系统是提高了文档的可用性、易用性和连贯性，使文档更加有效，是解决维护问题的有效途径。 动态文档系统问题分析 需要解决的问题是：软件文档的内容划分与获取、文档的存储与维护、文档的检索、软件文档的生成打印。 一、软件文档的内容划分成：语义文档、结构文档、过程文档 语义文档是对软件的功能、概念、

19、总体设计、流程、规约等用自然语言的描述，是软件人员根据规范在使用CASE工具编写并填入程序的文档，它也是为更全面的解释文档而灵活加入的额外信息。 结构文档是在软件设计工具、开发环境中对象的属性、构件间接口、构件间引用关系、软件的结构等的描述。利用词法、语法分析程序对整个系统的对象、构件进行识别、分析，获取上述描述并形成表格文件。 过程文档是对软件的设计、编码、维护过程中形成的过程描述和程序注释，如设计目的、设计人、时间等说明，利用开发环境对软件人员在设计、开发、维护过程中操作的记录形成操作跟踪。 二、程序与文档的统一存储与维护 根据程序与文档合一的概念和文档从程序中提取的要求，文档必须存放在程

20、序中，甚至文档固有的源代码中。结构如此的程序源代码的存储必须采用一种新技术对象仓储（Repository）技术，而不能采用流式文件，这样才能使程序与文档既结合又分离。程序与文档结合在一个对象仓储中，结合在统一的开发环境中；结合在修改代码时可以同时修改文档、修改文档时可以同时人工检查和修改程序，并在多次文档生成而不会丢失手工输入的文档。程序与文档应当分别存放在对象仓储中的不同表或不同的字段中，在编译与运行时分离。 三、文档的检索 对单个对象、构件文档的检索方式是若于文档存放在一个对象仓储中，它可以随源代码一起检索和维护。这种检索给分析和维护单个构件、对象提供文档支持。建立多种视图、编写程序对整个

21、系统进行文档的检索和获取，完成对整个系统的分析，对整个系统进行实时文档支持。这将在例子中较详细的描述。 四、软件文档的生成打印 编写程序检索和获取整个系统的文档，按照国家软件标准的文档式样建立文档模板并将按模板生成文档和利用文字处理软件强大的功能进行创建、编辑文档并打印。 根据上述分析，文档分布和获取对开发环境提出了要求：开发环境应该是设计工具、开发工具的集成，应该基于CASE技术、对象仓储技术、构件技术、OLE技术。基于CASE技术的开发环境；设计、开发、维护过程中形成的文档并植入程序代码中，使文档成为程序的一部分。基于对象仓储技术的开发环境，将文档与程序统一存储在对象仓储中方便检索。基于构

22、件技术的开发环境，便于识别、获取构件，分析、形成结构文档和过程文档。基于OLE等技术使文档可以很好地利用Word等文档处理软件。 动态文档系统的一个应用实例 广州电信科技开发有限公司自行设计、开发的名为九七系统的庞大的电信管理计算机系统自1997年投产验收后，将长期用于生产，维护工作非常重要和紧迫。这为动态文档系统提供了需求和试验场所。在长期维护的过程中，体会到好文档的重要性并提出了程序文档合一的概念，这为动态文档系统提供了理论基础。九七系统是使用Uniface开发环境。这种开发环境采用了CASE技术、对象仓储技术、构件技术，这为动态文档系统提供了技术支撑。 一、广州电信动态文档系统的建立步骤

23、 1. 理解Uniface、Oracle工具的开发环境，规划语义文档在各级对象中存放的表与字段，并根据工具的特性制定填写的规则。 2. 寻找结构文档、过程文档在Uniface、Oracle工具中存放的表与字段。 3. 在设计、开发和维护软件的过程中对这些表或字段按照规则进行填写。 4. 建立一整套模板使文档结构与信息源建立映像，包括：数据字典模板、设计文档模板、结构文档模板、开发过程文档模板等。 5. 将这些模板组装成文档系统，并使它独立于开发目标系统。 广州电信动态文档系统的组成可以分为文档查询、维护记录查询、文档生成。 文档查询不仅包括构件说明与数据描述，而且包括对构件与数据之间的关系的描

24、述，是实时的联机文档查询系统。维护记录查询是对软件维护过程中的各个环节进程进行记录与追踪，用于规范维护工作。它包括问题报告、问题分析、错误定位、维护设计、维护执行、确认测试、维护评审、维护提交、问题跟踪等。文档生成则是根据需要实时生成软件设计说明书。 二、程序与文档合一概念与动态文档系统的意义 广州电信动态文档系统的基本任务是辅助错误定位、维护影响分析、记录维护进程、生成文档。使用Uniface的开发环境开发的，可以安装在用Uniface开发的不同的应用系统中。该系统已经在九七计费系统的维护中发挥重要作用。 它推崇的程序与文档合一的概念，提出文档就是程序，程序就是文档的思路，文档融合在程序中的

25、构思并已实现，这一概念指导了软件人员进行有效地工作。合一的概念贯穿了设计、开发、维护整个软件周期，保证了文档之间的继承性和一致性，在设计、开发每一阶段是继承前阶段的程序和文档的结果。这样极大地消除了程序与文档、文档与文档之间的不一致性，加快了软件设计进度，提高了软件开发、维护的质量。它是软件工程在具体应用中的一种尝试，它从程序文档合一的角度出发，进一步规范软件设计、开发、维护。程序文档合一的概念为软件开发环境发展提供了一种思路；设计更好的对象仓储来满足开发、维护人员对程序文档合一的概念的需求。 动态文档系统的局限与发展 广州电信动态文档系统有很大的局限性，只能用于Uniface或Oracle开

26、发的系统中。目前的广州电信动态文档系统的构件的识别与获取主要依赖开发工具提供的构件和构件的特征进行识别的。这种动态文档系统难以在一些3GL工具未使用对象仓储技术、构件技术开发的软件中实现程序与文档的合一与分离。大型软件系统的环境是复杂的，往往采用了多种开发环境，如何对其他开发环境进行支持还要进行技术探讨和实践上的摸索。 另一个局限问题是目前的动态文档系统描述的是程序文档，其主要在编码、维护的过程中进行建设，系统进入维护阶段使用。如何使动态文档系统不仅对软件维护阶段进行支持，而且对软件的设计、开发阶段进行更多的支持？一种可能的解决途径是将软件复用技术拓宽到包括文档复用，包括程序复用、程序文档复用

27、和设计文档复用，而且将动态文档系统建立在基于这种软件复用系统之上。如何编写高质量“软件需求说明书”你的工程应该有个好的起点。一个小组要带领客户进入需求启发阶段而且你要写软件需求说明书。这份说明有些大，但客户会很重视，所以说明必须得到赞同。现在你正在设计其中的一个特性，已经发现了需求的一些问题。你可以用多种不同的方式解释需求15；需求9 的说明正好与需求21相反，你因该相信哪一个？需求24非常含糊，你根本不明白它的意思；你不得不花上一个小时与2位开发人员讨论需求30，只因为你们对其各有各的理解；并且，唯一能够澄清这些问题的客户没有给你们答复。你被迫破解众多需求的含义，并且你能预料到，如果你错了，

28、你要做大量的重复工作。 许多软件需求说明书（SRS）写得非常糟糕。任何产品的质量需要其原始材料的质量保证，糟糕的软件需求说明书不可能产出优秀的软件。不幸的是，几乎没有开发人员受过与需求的抽象、分析、文档、质检有关的教育。而且，没有非常多的好需求可以借鉴学习，部分原因是很少有工程可以找到一个好的借鉴，其他原因是公司不愿意将其产品说明书放在公共区域。这篇文章描述了高质量需求叙述和说明的几个特性（特点）。我们将用这些观点检查一些有缺陷的需求，带着痛楚重新编写。而且我会谈一些如何编写好的需求的提示。你也许想通过这些质量标准评估你的工程需求。对于修订，也许迟了，但你会学到一些有用的东西，并帮助你的小组在

29、下次编写出更好的需求。 不要期望能够编写出一份能体现需求应具备的所有特性的SRS。无论你怎么细化、分析、评论和优化需求，都不可能达到完美。但是，如果你牢记这些特性，你就会编写出更好的需求，生产出更好的产品。高质量需求叙述的特性我们如何从一些有问题的需求中分辨出好的软件需求？这一节将分别介绍需求叙述应体现的6个特性，下一节将从整体上介绍SRS文档应具备的特性。判断每个需求是否具备应有的特性的一种方式是由持有不同观点的工程资金管理人所作的正规检查。另一种有力的方法是在编写代码前依据需求编写测试例子。测试例子能够明确显现在需求中描述的产品行为（特性），能够显现缺陷、冗余和含糊之处。 正确：每个需求必

30、须精确描述要交付的功能。正确性依据于需求的来源，如真实的客户或高级别的系统需求说明书。一个软件需求与其对应的系统需求说明书相抵触是不正确的（当然，系统需求说明书本身可能不正确）。只有用户的代表能够决定用户需求的正确性，这就是为什么在检查需求时，要包括他们或他们的代理的关键所在。不包括用户的需求检查就会导致开发人员的：“这是没意义的”，“这可能是他们的意思”等众所周知的猜测。 可行性：在已知的能力、有限的系统及其环境中每个需求必须是可实现的。为了避免需求的不可行性，在需求分析阶段应该有一个开发人员参与，在抽象阶段应该有市场人员参与。这个开发人员应能检查在技术上什么能做什么不能做，哪些需要需要额外的付出或者和其他的权衡。必要性：每个需求应载明什么是客户确实需要的，什么要顺应于外部的需求，接口或标准。每个需求源于你认可、具有权说明需求的原始资料，这是考虑必需的另外情形（译注，此句翻译不顺，请参照原文：Another way to think of “necessary” is that