程序员写文档的重要性

写文档的重要性

对于软件相关行业，在学校或单位大家也许都已经注意到了，除了要编写的程序、绘制设计图之外，还有一个重要的工作便是写文档。为什么要写文档呢？因为我们要把自己做的东西展示出来，不光展示给同行看，可能还要展示给其他岗位上的工作人员看，甚至展示给用户看。如果我们只是会写程序，不会在文档中恰当且优雅地描述自己的想法，那么就真正的成为“码农”了。

有关文档书写，我印象很深的问题有如下几个方面：

我们每天都会收发很多邮件，我仔细看了一下，很多邮件里面的内容要么语句不通顺、要么有很多错别字、要么误用或没有标点符号。很多时候，从不同的角度理解，一封邮件有很多不同的意思，让人感觉不知道它究竟要表达一个什么意思，这样极大地降低了工作的效率。
除了代码之外，项目也会包含了大量的文档。打开大部分文档，看到的第一眼，我就有这几种感觉：排版不工整、格式不正确、语句不通顺、错别字连篇。一看就知道作者没有认真写文档，并且语句的表达和组织能力也不强。
在项目小组成员讨论的时候，大家几乎都在说怎样把程序写好，而没有提到在文档书写方面应如何努力去改进。大家似乎一致认为开发人员的职责就是把程序写好，其它什么的都是其次的。

有关计算机软件的传统定义为：软件是计算机系统中与硬件相依存的另一部分，软件包括程序、数据及其相关文档的完整集合。注意，这里面就提到了“相关文档”，如果文档没有写好，那么软件也不能算是优秀的软件。事实上，软件功能健全，而由于文档原因出现故障的情况还时有发生。

一般说来，在软件开发过程中，不同阶段涉及到的主要文档如下图所示：

可见，在软件的不同阶段，需要编写不同的文档。在计划阶段，需要编写详细设计文档、单元测试方案文档和集成测试方案文档等；在开发阶段，也是这几个文档，不过是修订版，因为我们在实际开发过程中，会发现之前设计不合理的地方或者是考虑不周的地方，这就需要对之前的文档进行修改；在测试阶段，要编写单元测试报告、集成测试报告和系统测试报告等；在软件的发布阶段，要编写安装手册、用户手册、升级指导书等，这些文档主要是面向现场支持人员和用户的，因此要尽量写得通俗易懂，千万不要有模棱两可的情况存在，否则就只有等待用户的投诉了。

要想写好文档，我们需要首先纠正一个观念：文档不重要。要把文档放在与程序同等重要的位置。

如何写出高质量文档？

那么，我们如何才能写出高质量的文档呢？我认为可以从如下几个方面着手：

改变文档为辅的观念，在平常的工作中，对于自己编写的每一份文档，均认真对待。
对于邮件的编写，要把自己想说的话准确地表达出来，在发送邮件之前，再看一下内容是否完整、是否还有错别字、语句是否通顺等。
在编写文档的过程中，要严格参照项目组规定的模板来完成。在写完文档之后，对文档进行语法检查，以纠正错别字和有语法错误的地方。一般说来，有语法错误的语句下面会有一条绿色的波浪线。在提交文档之前，再通读一下整个文档，看是否还有疏漏和不足。
在工作之余，可以读一些能够提高语言表达能力和写作能力的书籍或文章，看一下别人是怎样清晰地阐述自己思想的。例如，经常阅读CSDN上面优秀博主的博文就是一个提高自己写作能力的好办法。

总的说来，和做其它事情一样，书写文档也反映了一个人的态度问题。写出高质量的文档，不仅可以提升个人的形象（如果你看到一篇好文档，是不是也对作者有较高的评价？），还能够提升产品在客户心中的形象。如此分析，多花些心思来书写文档真的是很有必要。

要想做好一件事情，需要我们从各个方面来努力。在开发软件的过程中，写好代码很重要，清楚明了地在文档中表达自己思想同样非常的重要。“代码”和“文档”就像是一个人的左膀右臂，一定要让两者均衡发展，而不能够只顾其一。

程序员写文档的重要性相关推荐

好程序员技术文档HTML5开发中的javascript闭包
好程序员技术文档HTML5开发中的javascript闭包,事实上,通过使用闭包,我们可以做很多事情.比如模拟面向对象的代码风格;更优雅,更简洁的表达出代码;在某些方面提升代码的执行效率,同时避免对命 ...
天下程序员苦文档久已 | 《活文档》第一波短评
小伙伴们都知道,这是我们最近刚刚上架的一本书.这本书切中了不少程序员的痛点,因此,一上架就成为大家抢购的图书,最近一周一直稳居新书销量榜榜单. 除了预览版大佬们推心置腹的推荐,我们已经收获了第一批读者 ...
漫画 | 程序员管理文档和普通人有什么不同？
大家好哇~ 欢迎来到波波和阿菌神奇的"科普"频道! 今天,我们为大家介绍程序员是如何怎么存档并管理文件版本的. 我们先从日常生活讲起. 阿菌这坏小子有时会想回到自己的过去,比如说回 ...
程序员交接文档_一个.NET程序员 2019 跳槽3次的悲惨故事
2019年是值得深思的一年,在找工作上没有那么用心,导致碌碌无为,在这里我建议大家找工作的时候不要太着急...要不然会被逼疯的,一定不能被"工作"挑,一定要做到挑"工作& ...
这款即将开源的编辑器可能是最适合程序员的文档工具！
作为程序员,我经常需要写技术文档,之前也用过很多文档工具,比如有道云笔记,石墨,腾讯文档等. 我感觉他们大同小异,无外乎是文档编写.分享.协作这些功能,就像Word的简化版和在线版. 朋友曾经给我多次 ...
为什么程序员都不写文档？
‍‍‍ ‍ [CSDN 编者按]对于程序员来说文档可能是他最大的软肋.一些被称之为高手的程序员,往往是文档方面的处理会偏弱.不管这个程序员是在大公司.还在小公司.不管程序是写文档的.还是不写文档的,大 ...
java开发文档怎么写_程序员该不该写技术文档，怎么写文档，易懂又能提升自己...
最近公司项目的调用量突然涨了一大波,很多系统都纷纷扛不住了,于是需要对系统进行优化,系统优化的第一步,便是梳理业务! 在这个过程中,经常出现了这样一些情况,发现数据库的某些字段,没有注释,也没有一定的 ...
程序员都讨厌写文档？这4个工具让你事半功倍
长按识别上方二维码,关注公众号:后端面试那些事回复"报告",获取你的GitHub年度报告! 对于一般的程序员来说,花费数小时来创建代码或修改现有代码只是一天工作中的一部分,简而言 ...
从程序员到项目经理（二十九）：怎样写文档
在软件项目中,文档既是一项的重要成果,也是项目管理的有力工具.通过文档,可以稳定.明确的传达信息,实现项目内的有效沟通.所以写文档对项目经理来说,是一项必备的技能. 然而很多项目经理害怕写文档,似乎 ...

程序员写文档的重要性

程序员写文档的重要性相关推荐

最新文章

热门文章