阅读更多

7顶
0踩

研发管理

翻译新闻 10 个项目文档最佳实践

2012-11-21 16:57 by 副主编 wangguo 评论(9) 有8009人浏览
在软件开发和维护过程中,文档是必不可少的资料,它可以提高软件开发的效率,保证软件的质量,而且在软件的使用过程中有指导、帮助、解惑的作用。尤其在维护工作中,文档的重要性更是不言而喻。

本文整理了软件开发中10个最佳的文档编写实践,希望能对你的工作有所帮助。

1.  将编写文档作为开发工作中的一个重要环节(例如,占用总开发时间的10%)。在软件开发中,不能没有文档,但如果编写文档占用了大部分的时间也不合适。可以根据需要制定代码文档、需求说明文档、设计文档、测试文档、用户手册等,在制定完成后,可以通过版本控制工具或基于Web的平台来管理和共享这些文档。

2.  代码文档非常重要的。最好的方式是编写“自说明”的代码,变量、方法、类、包等名称必须是有意义的,代码流必须是清晰的。对于非常复杂的代码段,可以包含简短的注释行。还可以在代码中添加相关的标签或注释,自动生成Javadoc文档。

3.  对于将来接手的开发者,可以为他们准备一些简短、实用的设计文档,其中需要包含关键设计特性和UML图等,无需出现大量不必要的信息。

4.  需求/问题/未交付项目/功能点跟踪文档也相当重要。使用跟踪工具将会使这项工作更加有效率,这些工具可以帮助你完成一些像快速搜索、编辑等方面工作,并可以生成纯文本文档。

5.  测试跟踪文档也很重要。可以使用一些工具来记录测试场景和测试结果,并附上一些相关的需求。这样,可以很容易地监视软件的功能状态。

6.  文档是一个持续性的工作,开发人员应该随时更新或重新生成这些文档的最新版本,直到开发进程结束。如果一个文档不是最新的,那么它毫无价值。

7.  对于文本形式的文档,版本相当重要。每一个新的文档,必须有一个新的版本号(版本号由公司的版本管理策略来定),还需要将这些信息记录在版本跟踪表中,以便更好地跟踪。

8.  有一个统一的文档模板。文档的页眉、页脚、标题、字体大小必须一致,这样可以增强可读性。还可以做得更好,比如加上封面、目录、图表、词汇表等。

9.  还需要注意文档格式、使用的语言、错别字等。输入错误、不一致的表格大小、缩进等问题,可能会分散阅读者的注意力。

10.  将项目中学到的经验记录下来,并分享给其他人。开发者在每个项目中都可能会得到一些实用的经验(比如架构、代码、配置等),而这些经验信息不会出现在标准的开发文档中。开发者要不断积累并分享这些经验,这可能会加快当前的开发进度,而且对于将来做一些有挑战的工作或者重复性的工作,会有很大的帮助。

英文原文:10 Software Documentation Best Practices
7
0
评论 共 9 条 请登录后发表评论
9 楼 transist 2012-11-22 20:03
在文档的清晰和简洁上做个平衡,太简洁可能其他人读不懂,太清晰花时间多,并且在需求的不断变动中容易带来维护文档的压力。不更新的文档可能比没有文档危害更大。
8 楼 javaEEdevelop 2012-11-22 17:32
    
7 楼 demonkind 2012-11-22 16:46
  
6 楼 zhongmin2012 2012-11-22 09:43
文档确实很重要,项目团队必须养成跟踪文档为的习惯,否则出现问题就不好跟踪了
5 楼 gaobusi 2012-11-22 09:34
   
4 楼 Tomcat911 2012-11-22 09:22
  
  
3 楼 骨之灵魂 2012-11-21 23:37
       
2 楼 freezingsky 2012-11-21 19:47
  
1 楼 lsjinpeng 2012-11-21 19:18
   

发表评论

您还没有登录,请您登录后再发表评论

相关推荐

Global site tag (gtag.js) - Google Analytics