为了使软件文档能起到前节所提到的多种桥梁作用,使它有助于程序员编制程序,有助于管理人员监督和管理软件开发,有助于用户了解软件的工作和应做的操作,有助于维护人员进行有效 的修改和扩充,文档的编制必须保证一定的质量。质量差的软件文档不仅使读者难于理解,给使用者造成许多不便,而且会削弱对 软件的管理(管理人员难以确认和评价开发工作的进展),增高软件的成本(一些工作可能被迫返工),甚至造成更加有害的后果 (如误操作等)。
造成软件文档质量不高的原因可能是:
· 缺乏实践经验,缺乏评价文档质量的标准。
· 不重视文档编写工作或是对文档编写工作的安排不恰当。
最常见到的情况是,软件开发过程中不能按给出的进度, 分阶段及时完成文档的编制工作,而是在开发工作接近完成时集中人力和时间专门编写文档。另一方面,和程序工作相比,许多 人对编制文档不感兴趣。于是在程序工作完成以后,不得不应付一下,把要求提供的文档赶写出来。这样的做法不可能得到高质量的文档。实际上,要得到真正高质量的文档并不容易,除去应在认识上对文档工作给予足够的重视外,常常需要经过编写初稿,听取意见进行修改,甚至要经过重新改写的过程。
高质量的文档应当体现在以下一些方面:
①针对性
文档编制以前应分清读者对象,按不同的类型、不同层次的读者,决定怎样适应他们的需要。例如,管理文档主要是面 向管理人员的,用户文档主要是面向用户的,这两类文档不应像开发 文档(面向软件开发人员)那样过多地使用软件的专业术语。
②精确性
文档的行文应当十分确切,不能出现多义性的描 述。同一课题若干文档内容应该协调一致,应是没矛盾的。