程序员既要写好代码，又要写好文档

程序员是否应该注重文档的编写？这是一个看似很小但却比较重要的问题。软件除了程序和数据外 还包括文档。其次 如果程序员只是会写程序 不能在文档中恰当且优雅地描述自己的想法 那么就真的是"码农"了。

写文档的重要性

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

我注意了一下 周围的同事会写高质量文档的确实很少。李开复老师在《浪潮之巅》的序言中说到："我认识很多顶尖的工程师 但具备强大叙事能力的优秀工程师 我认识的可以说是凤毛麟角。"确实 我所认识的同事 能够在文档中清晰地表达自己想法的也很少。

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

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

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

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