13.2.3 软件文档的编写要求
为使软件文档能起到多种桥梁的作用，使它有助于程序员编制程序，有助于管理人员监督和管理软件的开发，有助于用户了解软件的工作和应做的操作，有助于维护人员进行有效的修改和扩充，文档的编制必须保证一定的质量。
如果不重视文档的编写工作，或是对文档编写工作的安排不当，就不可能得到高质量的文档。质量差的文档不仅使读者难于理解，给使用者造成许多不便，而且会削弱对软件的管理，提高软件成本，甚至造成更加有害的后果。
高质量的文档应体现在以下几个方面。
（1）针对性。文档编制以前应分清读者对象。按不同类型、不同层次的读者，决定怎样适应他们的需要。例如，管理文档主要是面向管理人员的，用户文档主要是面向用户的，这两类文档不应该像面向开发人员的开发文档那样过多地使用软件的专用术语。
（2）精确性。文档的行文应当十分确切，不能出现多义性的描述。同一课题的几个文档的内容应当是协调一致，没有矛盾的。
（3）清晰性。文档的编写应力求简明，如有可能，配以适当的图表，以增强其清晰性。
（4）完整性。任何一个文档都应当是完整的、独立的，它应自成体系。例如，前言部分应做一般性介绍，正文给出中心内容，必要时还有附录，列出参考资料等。还有，同一课题的几个文档之间可能有部分内容相同，这种重复是必要的。不要在文档中出现转引其他文档内容的情况。例如，一些段落没有具体描述，而用“见XX文档XX节”的方式，这将给读者带来许多不便。
（5）灵活性。各个不同软件项目，其规模和复杂程度有着许多实际差别，不能一律看待。
1）根据具体的软件开发项目，决定编制的文档种类。软件开发的管理部门应该根据本单位承担的应用软件的专业领域和本单位的管理能力，制定一个对文档编制要求的实施规定。主要是：在不同条件下，应该形成哪些文档？这些文档的详细程度如何？该开发单位每一个项目负责人都应当认真执行这个实施规定。
对于一个具体的应用软件项目，项目负责人应根据上述实施规定，确定一个文档编制计划。其中包括：
①应该编制哪几种文档，详细程度如何；
②各个文档的编制负责人和进度要求；
③审查、批准的负责人和时间进度安排；
④在开发时期内各文档的维护、修改和管理的负责人，以及批准手续；
⑤有关的开发人员必须严格执行这个文档编制计划。(https://www.daowen.com)
2）当所开发的软件系统非常大时，一个文档可以分成几卷编写。
①项目开发计划分为质量保证计划、配置管理计划、用户培训计划、安装实施计划。
②系统设计说明书分为系统设计说明书、子系统设计说明书。
③程序设计说明书分为程序设计说明书、接口设计说明书、版本说明。
④操作手册分为操作手册、安装实施过程。
⑤测试计划分为测试计划、测试说明书、测试流程、测试用例。
⑥测试分析报告分为综合测试报告、验收测试报告。
⑦项目开发总结报告也可分成项目开发总结报告、资源环境统计。
3）应根据任务的规模、复杂性、项目负责人对该软件的开发过程及运行环境所需详细程度的判断，确定文档的详细程度。
4）对国标GB8567-88《计算机软件产品开发文件编制指南》所建议的所有条款都可以扩展，进一步细分，以适应需要；反之，如果条款中有些细节并非必要，也可以根据实际情况压缩合并。
5）程序的设计表现形式，可以使用程序流程图、判定表、程序描述语言或问题分析图等。
6）对文件档的表现形式，没有规定或限制，可以使用自认语言或者使用形式化的语言。
7）当国标《计算机软件产品开发文件编制指南》中所规定的文档种类不能满足某些应用部门的特殊需要时，可以建立一些特殊的文档种类要求。这些要求可以包含在本单位的文档编制实施规定中。
（6）可追溯性。由于各开发阶段编制的文档与各个阶段完成的工作有密切的关系，前后两个阶段生成的文档，随着开发工作的逐步延伸，具有一定的继承关系，在一个项目各开发阶段之间提供的文档必定存在着可追溯的关系。例如，某一项软件需求，必定在设计说明书、测试计划，甚至用户手册中有所体现。必要时应能做到跟踪追查。
