文档恐惧症的分析

一、为什么不愿意写文档？

大部分开发人员不愿意编写文档，为什么呢？

1.写文档需要花费很多时间。

2.不愿意暴露自己的思想被别人评判。

3.文档编写得不好、没有充分发挥作用。

4.根据实践经验，并非不写文档，项目就干不下去。有很多客户也这样对我讲：“我们原来没有那么多文档，项目照样干，客户也一样验收付款啊！”。

5.如果写文档，很容易造成文档与实现不一致，文档的价值大大降低。

6.如果写文档，就不能只写一份文档，要写多份；为了写多份互相一致的文档，就要做评审，如果评审就要再产生各种评审记录；每次变更时，要修改多份文档，由此需要花费很多工作量，从感性认识上，这些工作都会降低项目的开发效率，导致工期的加长。

7.软件很简单，不需要写文档也能记住需求和设计思想。

8.实施CMMI或ISO 的企业，很多是为了通过评估、认证而规范，编写了很多文档，于是有人就抱怨：“CMMI就是文档”，于是文档的名声就更差了。

9.有很多人确实表达不出来，文字表达能力比较差。

二、文档的作用是什么？

文档与口头交流是两种沟通的方式。

1.口头交流有如下的特点：

•  即时性，这个时刻说的话，如果不录音，第二天无法重现了。
• 综合性，讲话时所处的场景信息，讲话者的语音、语调、神态等都是对语言的含义起到了丰富的辅助作用，而文档则不能将所有的信息包含在里面。
• 高效性，口头交流传达信息的速度比较快，可以在短时间内传达比较多的信息。但是写文档需要花费的时间比口头交流要慢的多。
• 双向性，沟通的双方可以有问有答，对沟通内容的正确性进行实时确认。
• 模糊性，口头交流的双方可能存在误解。

2.文档具有如下的特点：

• 正式性，文档是一种正式的沟通方式，有利于沟通的双方做正式的验证与确认。
• 严密性，相比口头交流而言，文档可以做到低二义性，降低沟通双方存在误解的可能性。编写文档的过程实际上也是一种思考的过程，通过编写文档强制作者能够想清楚、写清楚。
• 可重复性，文档是不随时间的推移，随时重现的，一旦形成了一份文档，人们可以在任何时间来阅读它，而并不需要文档的作者在场。文档可以永久存储，可以方便检索，可以经济地存档，可以为多人共享。

    综上所述，如果需要描述的比较严密、完备、无二义性，文档作为一种正式的沟通工具远比口头交流更加有效。但是文档不能解决所有的沟通问题，需要辅助以口头交流，二者是互补的，文字不能替代语言，语言也不能替代文字，在软件开发的过程中尤其是这样。如果不写文档，在实践中确实存在很多问题，比如理解不一致、沟通混乱、返工、无法维护等等。

三、应该何时写文档？

1.我们需要思考需要文档的目的，根据目的来判断：

• 要不要写文档？如果不写文档，如何实现你的目的？
• 文档是写给谁看的？
• 文档中的内容应该有什么？
• 文档应该由谁来写？
• 何时来写？

2.比如对于设计文档：

1)假设1：假如你的目的是：为了便于将来维护软件（注意我这里说“假如是这个目的”，因为很多公司写设计文档的目的不仅仅是为了维护），如果是基于这个目的，我们来回答上述的几个问题：

要不要写文档？如果不写文档，如何实现你的目的？需要！

文档是写给谁看的？维护人员！

文档中的内容应该有什么？ 程序的设计思想！核心算法！类之间的关系！

文档应该由谁来写？ 程序员！

何时来写？编码完成以后！

怎么写？可以用工具对代码进行逆向工程，然后再由程序员添加注释！

2)假设2：假如你的目的是为了评价设计思想的正确性，如果是基于这个目的，我们来回答上述的几个问题：

要不要写文档？如果不写文档，如何实现你的目的？未必需要写文档！我们可以让设计人员在白板上解释说明其设计思想，大家进行讨论和评审！如果不写文档，则我们需要增加面对面沟通的工作量。

3)假设3：假如你的目的是为了评价设计思想的正确性，并且便于QA进行审计，如果是基于这个目的，我们来回答上述的几个问题：

     要不要写文档？如果不写文档，如何实现你的目的？未必需要写文档！当设计人员在白板上解释说明设计思想，我们可以邀请QA人员进行实时的监督这个活动的执行，也未必一定要求每次设计思想的评审时，QA都参加，也可以抽查。QA审计的方法有多种：查文档记录、实际参与、访谈参与的人员。

4)假设4：假如你的目的是为了评价设计思想的正确性，并且为了将来维护软件，如果是基于这个目的，我们来回答上述的几个问题：

要不要写文档？如果不写文档，如何实现你的目的？需要写文档！

文档是写给谁看的？编码人员，设计专家，维护人员。

文档中的内容应该有什么？ 程序的设计思想！核心算法！类之间的关系！

文档应该由谁来写？ 程序员！

何时来写？编码之前编写设计文档！

怎么写？遵循公司的标准规范或者项目组自己定义的格式编写设计文档，并进行设计文档的评审。当发生设计思想变更时要修改设计文档，保持设计文档与代码的一致性。或者在编码结束后，要对设计文档和代码的一致性进行检查，修改存在偏差的地方，确保一致性。

3.也可以尝试定义一些基本的规则，比如：

• 当项目组超过3个人时就必须写文档了
• 对于将来要复用的东西必须写文档
• 对于客户要求的文档必须写
• 项目组新手比较多时必须写文档
• 产品开发的项目必须写文档
• 承诺是不可以省略的
• 开发周期比较长的项目必须写文档
• ……