10 个项目文档最佳实践

7顶
0踩

2012-11-21 16:57 by 副主编 wangguo 评论(9) 有7993人浏览

开发文档项目

在软件开发和维护过程中，文档是必不可少的资料，它可以提高软件开发的效率，保证软件的质量，而且在软件的使用过程中有指导、帮助、解惑的作用。尤其在维护工作中，文档的重要性更是不言而喻。

本文整理了软件开发中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

发表评论

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

相关推荐

IT项目管理最佳实践- .pdf

IT项目管理最佳实践- .pdfIT项目管理最佳实践- .pdfIT项目管理最佳实践- .pdfIT项目管理最佳实践- .pdfIT项目管理最佳实践- .pdfIT项目管理最佳实践- .pdfIT项目管理最佳实践- .pdfIT项目管理最佳实践- .pdf

第一章欢迎来到Python世界！

蒙提·派森:Monty Python,也称“蒙地蟒蛇”。是英国的一个六人喜剧团体，其七十年代的电视剧和八十年代的电影作品红极一时。贵铎·范·罗萨姆就是该团体的忠实影剧迷，故而将本语言命名为Python。这里的IDLE 指的是其成员艾瑞克·艾多（Eric Idle ）

你好欢迎你的到来

0.1欢迎来到C语言的世界（教程介绍）

大家好！咳咳，好吧，其实我心里也没底我说的这个“大家”到底能带至多少人→_→，不过作为一个逗比，我就姑且认为有同样逗比的小白白们能来读读我写的逗比教程，想想的确是个逗比的逗比……………… 我先来自我介绍一下，我叫逗比……呸……我叫小豪，至少我的朋友是这么叫我的，当然了，如果你觉得，我确实确实是个大逗比的话，那你就叫我逗比好了…… 我并不是哪个世界级软件公司的大侠，虽然我希望自己以后能变成大侠（

第一章欢迎来到Silverlight和WPF的世界

在完成本章学习后，你将能够：识别Silverlight和WPF的基本技术区分设计师和开发者的角色认识在Expression Studio 4中的产品理解Visual Studio是如何适应你的设计过程新鲜的和持续变化的技术已经并且将一直会吸引尖端的人们。感受和使用它们就好像在与未来打交道。在我们之中最幸运的人开始设计和开发基于这些新技术的东西并且创作惊人的新软件。当今时代终端使用者对先前静态的开发标准特性、不断增加的友好期待和互动交流感到厌烦。设计在我们今天用的许多产品中是一种竞争优势。一

根据最佳实践和简单的假设自动生成laravel项目的swagger文档

IT项目管理最佳实践- .docx

IT项目管理最佳实践- .docxIT项目管理最佳实践- .docxIT项目管理最佳实践- .docxIT项目管理最佳实践- .docxIT项目管理最佳实践- .docxIT项目管理最佳实践- .docxIT项目管理最佳实践- .docxIT项目管理最佳实践- .docx

远程软件工程师的10个最佳实践

【引子】最近又要关注研发效率，《如何提高团队的研发效率呢？》是一些总结与思考，当然，阅读与学习也必不可少，这一篇编译自 “The 10 Best Practices for Remote ...

工程项目管理若干最佳实践.pptx

【软件项目文档编写最佳实践】培训课程

来自中培教育的【软件项目文档编写最佳实践】培训课程，仅供大家参考。版权归原组织所有。

某供电公司业务流程优化设计项目最佳实践差距分析详细报告.pptx

项目管理最佳管理实践文档

项目经理必备的各类文档，相当实用。包含了各类常用的图表模板。

fe-better-practice：基于React的前端项目最佳实践探索文档

杜米应用入门安装依赖项$ npm i 启动开发服务器， $ npm start 建立网站应用程式， $ npm run build

XX公司业务流程优化设计项目最佳实践评估报告.pptx

工程项目管理若干最佳实践教材.pptx

XX公司业务流程优化设计项目最佳实践评估主报告.pptx

ASP在线学习网站系统毕业课程源码设计+论文+英文翻译

编号：94 (1)课堂学习模块这个模块主要是提供给学习者学习内容，为静态内容。系统按各个科目分目录进行存放，并在菜单页面放置了链接。该模块主要是为学生所使用，学习在登录系统后可直接选择进入本模块，通过对静态页面的浏览达到学习的目的。该功能设计应美观、便捷，使学生能够以一个较愉快的心情进行学习，以提高学习的效率。另外教师发布的教案可能有各种形式，如htm、doc、ppt、avi等，但在通常情况下，这些教学内容都是静态内容，因此按类别及内容分类在网站上发布即可。 (2)作业模块此模块为学生和教师共同使用，但根据权限的不同使用不同的功能。学生主要使用作业上传功能和查询作业分数功能，而教师主要使用网上下载作业并进行作业评分的功能。因此，系统需要提供以下功能：上传：将作业上载到指定地点，并按某种方式进行标识。批阅：教师可对作业进行批阅判分。 (3)在线答疑模块网络课程的学习不同于一般的单机课件的学习，主要的一点在于学习环境的不同，它为学习者的学习交流、协作创造了条件，这是网络学习的一个优势。在线答疑主要是学习者和教师之间，学习者和学习者之间，就知识本身或相关话题的讨论。

7顶0踩