好的软件文档怎样产生影响

我跟大多数人一样，也明白软件文档的价值。遗憾的是，我很少在着手完成一项任务之前阅读其文档。相反，我经常跟那些看不清事实真相的父母亲一般，将他们的孩子的自行车都收起来了，却残留下一两个部件。

如果我们了解了文档的价值，那么为什么又不去多用用它呢？至于初学者，大多数的软件文档都会遭遇以下问题中的一些：

·     糟糕的语法和/或拼写错误的词语

·     不完善

·     过期或不准确

·     冗长的

·     不清楚的首字母缩写词或专门述语

·     很难在该文档中找到有用信息及方便地操作文档

存在这样一些问题的最主要的原因在于，软件文档经常被看作是次要的。项目预算被迫优先考虑在发展过程中所涉及的主要行动，在那里，管理很容易就能估量出利益的大小。需要证明文档所能带来的益处通常都是主观的，它通常被看作是避免一个消费花费而不是产生ROI（投资回报）。许多项目经理总是认为文档只要以最小限度的满足客户的要求即可。

软件文档的另一个麻烦的根源则与作者有关。许多应用软件开发经理认为软件文档是软件发展中的一个标准部分，因此，需要开发人员根据代码来编写软件文档。

尽管从理论上来看这很好，不过它并没有考虑开发人员作为这一文档作者的能力。需要指出的是，技术人员是经过培训来做开发而不是写作。为了弄清这个问题，一些应用程序开发经理试图通过雇用一些科技作家或商业分析家来帮助提高他们的软件文档的质量。这就引起了另一个截然相反的问题：科技作家和商业分析家在技术上通常都很有限。

上述问题的解决方案取决于对该文档提出的问题以及有意于阅读该文档的人员。通常的法则是，书写文档需要通过一种联合作业的途径，这一途径允许开发者和作者利用他们自己的实力。比如，如果有意于该文档的人员是一个系统设计师，那么开发者就应该为他提供详细的输入内容，但是要允许科技作家来组织并编辑那些内容，让它们在语法上说得通。如果不考虑有意于使用该文档的人员或已选定的作者，则此文档的质量会影响其可用性。你可以通过以下六种属性来衡量其可用性：

·     适用性：该文档是否提供相关信息？

·     适时性：这些信息是最新的吗？

·     精确性：这些信息是正确的吗？

·     完整性：这些信息足够详尽，而不是只突出某些具有压倒性优势的信息吗？

·     方便性：使用这些文档容易吗？

·     可用性：你可以凭直觉很快地找到信息吗？