软件文档编写存在的问题和解决办法的思考

和大多数人一样，我们明白软件文档的重要性，但不幸的是我们往往忽视它的产生和维护以及使用。

 

普遍在软件文档存在的问题：
错误的语法或拼错的词语
不完整
过时或不准确
过于冗长
未经解释的缩略语或专用术语
查找信息困难

存在问题的主要原因：
工程进度压力，优先考虑编码开发
编写文档需要花费成本，项目经理减少投入，只是装点门面
由开发人员编写文档
专用的技术文档编写者或业务分析师编写文档对技术部门把握不准确

解决方法：
写文档需要团队协作，开发人员和文档编写者利用彼此的长处，取长补短；如开发人员提供技术细节，然后文档编写者按照正确的语法组织和编辑内容。

文档质量评价标准：

• 应用性：文档是否提供相关信息
• 及时性：信息是否及时
• 准确性：信息是否正确
• 完整性：文档是否足够详细而不冗长
• 可得性：文档是否随时可得
• 可用性：你能否很快凭直觉找到所需信息

• 
  软件文档的目的：
  传达一个系统的技术要素和使用方法
  提供软件开发工程中需求、决策、行为、角色、职责的书面记录