优秀软件文档的必备要素

在项目开发完成了三分之二的时候，风险承担人对一个正在设计的特性提出疑问，提出了这样的问题：

为什么你花了400小时的时间构建一个全自动的销售点应用程序？我们只需要一个电子数据表来提交我们的销售信息。

当你拼命地试图回忆当初的需求会议的时候，你的反应只能是可怜说当初在项目开始阶段团队理解出现了问题。

当然，这是一个很极端的例子，但是却是在项目开发中经常出现。你可以将这个问题归结到需求管理之上。我将这个过程描述为一个包含五个阶段的反复过程，其目标是在项目的生命周期中管理项目开发的捕获、文档、跟踪和交付。下面是这五个阶段的一个简单描述：

第一阶段：初始化
这个阶段从项目请求开始，到项目被核准结束。这个阶段的目标是确定项目是否值得开发，与别的项目相比其优先级别如何。其步骤包括： 

初始项目请求。 
IT区域回顾。 
概要成本估算，CBA，或者预计的ROI。 

第二阶段：确定或启发
这个步骤是指详细需求的组织化的和结构化。它包括： 

最初的项目请求的回顾。
项目风险承担人的初步确定。

启发计划的完成。 
反复地执行需求启发步骤，包括会见、交流或其它技术。 
初步需求列表。 
商业规则的确定。 
文档，包括使用案例、上下文图表及其它更多内容。 
功能和非功能需求的正式创建。 
和大多数同行一样，我明白软件文档的重要性。不幸的是，在任务开始前我很少阅读文档。相反，我常常像视线不清的父母一样，在装配好他们孩子的自行车之后，还落下一两个零部件没装上。

 
 

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

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

·  不完整

·  过时或不准确

·  过于冗长

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

·  查找信息困难

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

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

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

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

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

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

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

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

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

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

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

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

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