为使软件文档能起到多种桥梁的作用，使它有助于程序员编制程序，有助于管理人员监督和管理软件的开发，有助于用户了解软件的工作和应做的操作，有助于维护人员进行有效的修改和扩充，文档的编制必须保证一定的质量。

如果不重视文档编写工作，或是对文档编写工作的安排不当，就不可能得到高质量的文档。质量差的文档不仅使读者难于理解，给使用者造成许多不便，而且会削弱对软件的管理(难以确认和评价开发工作的进展情况)，提高软件成本(一些工作可能被迫返工)，甚至造成更加有害的后果(如误操作等)。

(1)针对性：文档编制以前应分清读者对象。按不同的类型、不同层次的读者，决定怎样适应他们的需要。例如，管理文档主要是面向管理人员的，用户文档主要是面向用户的，这两类文档不应像开发文档(面向开发人员)那样过多使用软件的专用术语。

(2)精确性：文档的行文应当十分确切，不能出现多义性的描述。同一课题几个文档的内容应当是协调一致，没有矛盾的。

(3)清晰性：文档编写应力求简明，如有可能，配以适当的图表，以增强其清晰性。

(4)完整性：任何一个文档都应当是完整的、独立的，它应自成体系。例如，前言部分应做一般性介绍，正文给出中心内容，必要时还有附录，列出参考资料等。

同一课题的几个文档之间可能有些部分内容相同，这种重复是必要的。不要在文档中出现转引其他文档内容的情况。例如，一些段落没有具体描述，而用“见××文档x×节，，的方式，这将给读者带来许多的不便。

(5)灵活性：各个不同软件项目，其规模和复杂程度有着许多实际差别，能一律看待。

1)应根据具体的软件开发项目，决定编制的文档种类。

软件开发的管理部门应该根据本单位承担的应用软件的专业领域和本单位的管理能力，制定一个对文档编制要求的实施规定。主要是：在不同条件下，应该形成哪些文档?这些文档的详细程度?该开发单位每一个项目负责人都应当认真执行这个实施规定。

对于一个具体的应用软件项目，项目负责人应根据上述实施规定，确定一个文档编制计划。其中包括：

• 应该编制哪几种文档，详细程度如何。
• 各个文档的编制负责人和进度要求。
• 审查、批准的负责人和时间进度安排。
• 在开发时期内各文档的维护、修改和管理的负责人，以及批准手续。
• 有关的开发人员必须严格执行这个文档编制计划。

2)当所开发的软件系统非常大时，一种文档可以分成几卷编写。例如，

• 项目开发计划可分写为：质量保证计划、配置管理计划、用户培训计划、安装实施计划等。
• 系统设计说明书可分写为：系统设计说明书、子系统设计说明书。
• 程序设计说明书可分写为：程序设计说明书、接口设计说明书、版本说明。
  -操作手册可分写为：操作手册、安装实施过程。
• 测试计划可分写为：测试计划、测试设计说明、测试规程、测试用例。
• 测试分析报告可分写为：综合测试报告、验收测试报告。
• 项目开发总结报告也可分写成：项目开发总结报告、资源环境统计。

3)应根据任务的规模、复杂性、项目负责人对该软件的开发过程及运行环境所需详细程度的判断，确定文档的详细程度。

4)对国标GB8567—88《计算机软件产品开发文件编制指南》所建议的所有条款都可以扩展，进一步细分，以适应需要；反之，如果条款中有些细节并非必需，也可以根据实际情况压缩合并。

5)程序的设计表现形式，可以使用程序流程图、判定表、程序描述语言(PDI，)、或问题分析图(PAD)等。

6)对于文档的表现形式，没有规定或限制。可以使用自然语言、也可以使用形式化的语言。

7)当国标《计算机软件产品开发文件编制指南》中所规定的文档种类不能满足某些应用部门的特殊需要时，可以建立一些特殊的文档种类要求。这些要求可以包含在本单位的文档编制实施规定中。

《软件产品开发文件编制指南》中给出了一个例子，利用求和法综合衡量12种考虑因素，来确定应编制文档的种类。使用这个方法的具体过程如下：

a．针对表所列的12种衡量因素，考察所开发的软件。对每一种因素给出一个分值，其范围从1到5。

b．把衡量所得的各个因素的值相加，得总和之值。

c．根据总和之值，对表表进行查找，确定应编制的文档的种类。

其中，数据要求说明书栏用**表示应当根据所开发软件的实际需要来确定是否需要编制这个文档。测试分析报告栏用*表示这个文档应该编写，但不必很正规。

(6)可追溯性：由于各开发阶段编制的文档与各个阶段完成的工作有密切的关系，前后两个阶段生成的文档，随着开发工作的逐步延伸，具有一定的继承关系，在一个项目各开发阶段之间提供的文档必定存在着可追溯的关系。例如，某一项软件需求，必定在设计说明书、测试计划、甚至用户手册中有所体现。必要时应能做到跟踪追查。

组织简介 | 联系我们 |   Copyright 2002 ®  UML软件工程组织 京ICP备10020922号

京公海网安备110108001071号