对文档编制的质量要求

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

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

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

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

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

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

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

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

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

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

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

　　应该编制哪几种文档，详细程度如何。

　　各个文档的编制负责人和进度要求。

　　审查、批准的负责人和时间进度安排。

　　在开发时期内各文档的维护、修改和管理的负责人，以及批准手续。

　　有关的开发人员必须严格执行这个文档编制计划。

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

　　项目开发计划可分写为：质量保证计划、配置管理计划、用户培训计划、安装实施计划等。

　　系统设计说明书可分写为：系统设计说明书、子系统设计说明书。

　　程序设计说明书可分写为：程序设计说明书、接口设计说明书、版本说明。

　　-操作手册可分写为：操作手册、安装实施过程。

　　测试计划可分写为：测试计划、测试设计说明、测试规程、测试用例。

原文转自：http://www.ltesting.net