我们为什么写文档？

写文档究竟是为了什么，现在大部分的文档写的都很形式，都是做个样子。很多团队都是先有代码后有设计说明，简直就是笑话。完全的形式主义，为了文档而写文档，完全把文档的意义给扭曲了。

l 文档帮助我们进行更好的沟通

这里就涉及到一个问题：文档写到什么程度为好？答案就是合格的文档不需要文笔多么的好，不需要文字多么多，不需要什么特别严格的格式；只需要能让他人看懂，能让他人拿到文档后不需要再向你咨询直接根据文档就能比较全面的了解这个系统，仅此而已。说起来容易做起来还是比较难的。

问过很多团队不写文档的原因，最多的回答就是为了“高效”的完成系统，但是纵观没有文档的开发似乎也并不高效，没有文档的情况下团队中往往充斥着以下对话。

A：我那的接口呢

B：你们要那的接口了吗？没有吧

A：谁说的，****时候不是给你说了我们要****接口了么！！

B：没有吧，不记得了

A：……

假如当时马上能拿出一份文档，那么到底是谁的责任就明确的多了，所谓有文档有真相就是这么个意思吧。况且如果真有文档的话，也不会发生上面的对话了。相信每个开发团队中的开发人员的阅读和理解中文文字的能力还是有的，不至于对照着文档还能落掉哪个方法丢掉哪个类吧。所谓好脑子不如烂笔头就是这个道理，所以说没有文档作保证，高效的交流什么的就是浮云。

l 文档帮助我们记录开发周期的点点滴滴

不要认为以后没有人看就不需要写文档了。

一个优秀的团队应该把每个开发过的项目中用到的东西，例如典型的技术，经典的算法，等等都应该以文档的形式保存下来。因为你的团队不可能只开发一次系统，下次可能开发别的系统但是很有可能用到这次开发过程中的部分技术或者部分算法等等更有甚者或者两个项目业务几乎一致完全可以把以前的架构拿过来用，这都不是不可能的。这样一来文档的巨大作用就体现出来了。

很多的团队没有及时的文档，请注意是及时的文档，不包括代码完成后补充的文档。虽然补充文档要比没有文档强的多，但是补充的文档有很多问题。比如记录工期不准确，记录所用到的技术或者算法不完全，补充的文档非常耗费时间等等。我们能顺手做而且又不得不做的事情为什么要单独拿出来做呢？。

l 文档可以帮助我们整理思路

没有文档需求岂不是之上谈兵。今天说个样，明天说个样，这系统还能做么？

没有概要设计或者详细设计，如果团队整个开发周期中如果人员不流动的话还好一点，人员万一流动就会出现文章前面说的那个情况：ctrl+ A 然后delete接着一群自恋的人就开始开辟自己的一片新世界了。这样的话等待整个团队的将是功能实现上的矛盾，工期的无限延长，但是如果有文档的话情况就大大不同了。

设计人员通过写文档可以对整个软件或者自己的模块有一个比较详细的了解，写文档说白了就是用文字编码。有一句很经典的话：能编码不一定能写好文档，但是能写好文档的一定可以很好的编码。画过UMl图的人都知道，简单的几条线要比几十行甚至几百行代码来的快。同样的道理文档作用也是如此，几行文字要比N行代码来的省事。由于UML毕竟是建模的语言不是真正的人类交流的语言，所以在与用户或者与水平比较低的团队队员之间交流过程中文档的作用就更加明显了。根据文档程序员就能直接编码才是优秀文档最理想的效果。

l 文档可以为我们节约时间

除了上文中说的没有文档的话交流没有合理的记录之外，没有文档的另一个弊端就是非常容易浪费双方的时间。很多团队感觉文档没用，于是整个团队之间最常见的交流方式是qq或者飞信，更有甚者直接口头交流。相互说你要什么接口我需要什么方法，重复的话说的不少，时间也耗费了不少，结果却很难令人满意。

显而易见，没有文档的交流（无论是qq、飞信还是口头）都是需要两个人同时参与的。整个过程如下：在你向别人传递信息的时候大脑是不断思考的，也就是说你是边说边思考，那么你的话必定是断断续续的，而且还很有可能是重复或者错误的。更加可悲的是在这短时间里对方必须等待你思考完毕以及你表达完毕，然后对方才能去理解你的意思，最后对方再把他理解的意思阐述给你听以确保理解无误。在这段时间里对方同样也在边说边思考，和上面的情况类似你也不得不等待他思考以及表述完毕，然后才能给予肯定。

算下来整个过程浪费了很多不必要的时间，如果加入用文档的话将是一个情况。前者把思路理顺后直接用文档的形式传递给后者，在前者写文档的时候丝毫不浪费后者的时间。后者拿到文档后直接理解传递过来的文档，理解的过程中也丝毫不浪费前者的时间。最后双方进行反馈，由于大家都已经阅读过文档相对而言准备的已经比较充分了，所以就可以直奔主题进入关键部分了，为整个团队节约了很多时间，效率自然而然就高了。