优秀软件文档的必备要素

《优秀软件文档的必备要素》由会员上传分享，免费在线阅读，更多相关内容在工程资料-天天文库。

1、优秀软件文档的必备要素在项目开发完成了三分之二的时候，风险承担人对一个正在设计的特性提出疑问，提出了这样的问题：为什么你花了400小吋的吋间构建一个全自动的销售点应用程序？我们只需要一个电子数据表来提交我们的销售信息。当你拼命地试图回忆当初的需求会议的时候，你的反应只能是可怜说当初在项目开始阶段团队理解出现了问题。当然，这是一个很极端的例子，但是却是在项鬥开发中经常出现。你可以将这个问题归结到需求管理之上。我将这个过程描述为一个包含五个阶段的反复过程，其目标是在项目的生命周期中管理项目开发的捕获、文档、跟踪和交付。下面是这五个阶段的一个简单描述：第一阶段：初始化这个阶段从项

2、目请求开始，到项目被核准结束。这个阶段的目标是确定项目是否値得开发，与别的项目相比其优先级别如何。其步骤包括：初始项目请求。IT区域回顾。槪要成本估算，CBA，或者预计的ROI。第二阶段：确定或启发这个步骤是指详细需求的组织化的和结构化。它包括：最初的项目请求的回顾。项口风险承担人的初步确定。启发计划的完成。反复地执行需求启发步骤，包括会见、交流或其它技术。初步需求列表。商业规则的确定。文档,包括使用案例、上下文图表及其它更多内容。功能和非功能需求的正式创建。和大多数同行一样，我明白软件文档的重耍性。不幸的是，在任务开始前我很少阅读文档。相反，我常常像视线不清的父母一样，在

3、装配好他们孩子的自行车之后，还落下一两个零部件没装上。如果我们明白文档的重要性，那为什么我们不更经常用它呢？然而，许多软件文档存在以下问题：?错误的语法和1/或拼错的词语?不完整?过时或不准确?过于冗长?未经解释的缩略语或专用术语?查找信息困难存在这些问题的主要原因是软件文档常常被退居次位。工程预算迫使我们优先考虑幵发过程中的主要活动，也就是那些可以看得到利润的地方。编写文档需要成本,因而它常常成为一项主观上的活动，而且通常被认为没有重要作用，应该尽量避免。许多项目经理认为客户不需要文档，它只是用来装点门面的。软件文档质量差的另外一个原因在于文档撰写者。许多应用程序开发经理

4、认为软件文档的编写是软件开发过程的一个标准组成部分，因此要求开发人员在编码的过程中产山文档。尽管这种做法在理论上行得通，但它没有考虑开发人员编写文档的能力。简单来说，技术人员是用来开发软件而不是编写文档的。为了解决这个问题，许多应用程序开发经理雇佣专业技术文档编写者或业务分析师,以期改进软件文档的质量。但这又遇到了另一个难题：专业编写者及业务分析师的技术水平有限。解决这个问题要考虑需要编写的文档以及文档的预期读者。一般的规则是,写文档需要团队协作，这样就允许开发人员和文档编写者利用彼此的长处，取长补短。例如，如果预期读者是系统设计师，开发人员需要提供技术细节，然后文档编写者

5、按照正确语法组织和编辑内容。不考虑预期读者或专门编写者，软件文档的质量取决于其可用性，可从以下6个方面去评价其可用性：?应用性：文档是否提供相关信息？?及时性：信息是否及时？?准确性：信息是否正确？?完整性：文档是否足够详细而又不会太过拘泥细节？?可得性：文档是否随时可得？?可用性：你能否很快凭直觉就找到所需信息？软件文档的最主要目标是传达一个系统的技术要素和使用方法。第二个目标是提供软件开发过程中的需求'决策，行为'角色和责任的书面记录。只有实现了这两个目标，软件文档才真正捉供了有意义的信息。