文档的重要性

听运营办王主任关于文档重要性的讲座听了两遍，虽然主要内容相似，但是每一次听都有很大收获，虽然上周五是第二次听，却仍然收获颇丰。

文档最重要的功能是“备忘”，而不是“沟通”。关于这两个功能，以前都深有感触的，但并没有系统性地划分主次。的确，文档的沟通功能是有限的，这个不仅取决于文档作者的表达水平与写作功底，而且与读者的背景知识有着重要依赖性。同一个文档，不论是设计类、需求类还是使用说明类，可能会有不同职责、岗位的读者，如果想写一份所有人都读得懂的文档显然是不太现实的，沟通并不是文档的主要作用。文档的主要作用是“备忘”，“好记性不如烂笔头”，随时通过文档记录查看以前的想法、做法，可以避免由于记忆不完整导致第二次决策的失误。公司是有现成的例子的，本来有个产品辛辛苦苦开发了一年，而开发人员陆续离职，等新人接手时发现文档不完整、不一致，导致无法平滑交接工作，最后决定重新开发一套软件，结果新版本完成后比旧版本的问题更多，原因就是原来已经解决的问题由于没有记录，在重新开发时没有考虑到。

当然，“沟通”也是文档的一个重要作用，但不充分，要想充分沟通还是需要小范围的面对面的交流，必要时需要一对一的交流。沟通功能最强的应该是用户使用说明书了，要力求做到用户通过使用说明书就可以了解产品的使用方法，不需要也没有条件进行额外的沟通，并且面对面沟通成本是非常高的，这个文档绝对的必要，应该没有人会去置疑。虽然文档不能达到充分沟通的目的，但可以解决多数的沟通，比如需求说明书、设计说明书，通过阅读这些文档可以了解多数基本内容，而仅需要对某些细节进行面对面的沟通，毕竟面对面的沟通成本是很高的。

说到文档用于维护的作用，其实应该也算作是备忘和沟通作用的一部分，如果没有文档维护时可能不知道维护的内容、步骤、注意事项等方方面面，通过文档可以解决绝大多数的维护问题，除非发现了新的系统BUG。

王主任说到他多年来的一点感悟，写文档最忌讳的一点――模板。这一点要真的让谁讲出来，实在很难讲出来，这应该是一个见仁见智的问题，但提到这个词，我立即就明白了他的意思，因为我对这点了有点儿想法。

模板对于新手，有着重要的启发与指导作用。因为新手写起文档经常不知道从哪里下手，模板告诉了他从哪儿开始，并给出了常用的提纲，指导着作者下一步写什么。更重要的是，模板一般都是有经验的人总结出来的，会给出很多新手想不到的一些方面。

模板本身也有副作用，会影响作者的思路。模板是一个通常只能适合多数情况下的框架，但并不是适合所有情况，如果一味地根据模板写文档，会限制作者的思路，也会束缚作者的表达方式，不一定总能写出好的文档。模板不是目的，重要的是把问题交待清楚，把观点说明白。我对这一点也是有点儿体会的，因为以前总碰到问题，所以经常会不使用模板，特别是对于一些问题点较多，比较复杂的地方，我倾向与用表格来描述，通过不断地修改形式，寻求一种既能包含足够的信息量，又比较简洁的形式。

话又说回来，文档都包括哪些内容呢？当然，那些Word、Excel、TXT等各种各样的纯粹用于记录事情的文件属于文档，而源代码文件本身也是文档的部分。其中，代码注释是非常重要的文档内容，尤其对于软件的维护升级起着非常重要的作用。设计说明书可以对软件开发的整体思路进行描述，而对于实现细节不可能一应俱全地详述，否则文档更新的成本会很高，而且造成代码与文档不一致的可能性也更大，反而更容易导致文档失效。文档注释，可以在程序员编程时随时对一些重要的事情，特别是对软件可靠性、稳定性有影响的注意事项，或者在解决某些特殊问题使用的一些小的技巧，都要比较清楚地通过注释写下来，也可以避免在更新时由于没有注意到某些小问题导致系统BUG。

并且，代码本身就是文档，而且是重要的沟通手段。代码可读性一直都是程序员讨论的一个热点问题，之所以追求可读性，也就是追求代码的“自描述”性，将代码本身作为文档看待，所以才会有了各种编程风格的讨论。

除了那些正规的文档，很多时候可以通过一些非正规的文档来提高软件开发的效率或提高软件质量，比如一个简单的BUG修改记录和心得，记录每一个BUG的从发现到解决的过程，久而久之就成了自己经验的总结，就是一批巨大的财富，甚至可以著书立说。

文档，除了正式的必要的软件开发过程文档有格式、内容要求外，开发者平时还可以记录一些非正式的内容，不需要拘泥于形式，只要有用就都记下来，养成随时记录的习惯，时间长了定会给自己一个巨大的惊喜。