优秀软件文档的必备要素

第二阶段：确定或启发

最初的项目请求的回顾。

项目风险承担人的初步确定。

和大多数同行一样，我明白软件文档的重要性。不幸的是，在任务开始前我很少阅读文档。相反，我常常像视线不清的父母一样，在装配好他们孩子的自行车之后，还落下一两个零部件没装上。

如果我们明白文档的重要性，那为什么我们不更经常用它呢？然而，许多软件文档存在以下问题：

•错误的语法和/或拼错的词语

•不完整

•过时或不准确

•过于冗长

•未经解释的缩略语或专用术语

•查找信息困难

存在这些问题的主要原因是软件文档常常被退居次位。工程预算迫使我们优先考虑开发过程中的主要活动，也就是那些可以看得到利润的地方。编写文档需要成本，因而它常常成为一项主观上的活动，而且通常被认为没有重要作用，应该尽量避免。许多项目经理认为客户不需要文档，它只是用来装点门面的。

软件文档质量差的另外一个原因在于文档撰写者。许多应用程序开发经理认为软件文档的编写是软件开发过程的一个标准组成部分，因此要求开发人员在编码的过程中产出文档。

尽管这种做法在理论上行得通，但它没有考虑开发人员编写文档的能力。简单来说，技术人员是用来开发软件而不是编写文档的。为了解决这个问题，许多应用程序开发经理雇佣专业技术文档编写者或业务分析师，以期改进软件文档的质量。但这又遇到了另一个难题：专业编写者及业务分析师的技术水平有限。

解决这个问题要考虑需要编写的文档以及文档的预期读者。一般的规则是，写文档需要团队协作，这样就允许开发人员和文档编写者利用彼此的长处，取长补短。例如，如果预期读者是系统设计师，开发人员需要提供技术细节，然后文档编写者按照正确语法组织和编辑内容。

不考虑预期读者或专门编写者，软件文档的质量取决于其可用性，可从以下6个方面去评价其可用性：

•应用性：文档是否提供相关信息？

•及时性：信息是否及时？

•准确性：信息是否正确？

•完整性：文档是否足够详细而又不会太过拘泥细节？

•可得性：文档是否随时可得？

•可用性：你能否很快凭直觉就找到所需信息？

软件文档的最主要目标是传达一个系统的技术要素和使用方法。第二个目标是提供软件开发过程中的需求，决策，行为，角色和责任的书面记录。只有实现了这两个目标，软件文档才真正提供了有意义的信息。