管理感悟：需要什么样的技术文档
红朝儒生
2016-4-16
关键字：管理 软件 文档
简介：通常的软件文档，不容易写好，要正确理解也难，事实上也没有人看。所以吾只要求有用的文档。
在软件行业，有一种文档迷信。什么意思？就是动不动就要求写技术文档，比如详细设计、概要设计。而程序员呢，在接手工作的时候，也迷信于文档。实际上，技术文档，基本没有用。
技术文档没用？是的。在二中（中兴）工作的时候，每开展一个项目，就要求出这样那样的文档。其实想想，哪里有那么多时间写文档？怎么办？抄吧，把别的项目文档拿过来，略略修改，评审的人也知道怎么回事，就算完成了任务。然后呢？这样的文档，会有人拿出来看第二遍吗？不会的。对工作有什么用处呢？没用。二中如此，别的公司也差不多。
一个文档，要有用，取决于很多因素：
程序运行正确。这个问题倒是不大。
作者理解正确。比如程序的原作者写文档，问题不大；如果维护者属于靠谱级程序员，应该也不存在问题。
作者表达正确。即作者能准确表达自己的想法，包括表达方式、表达用语、内容组织等等。比如，在适当的时机用表格、流程图等等。实际上，一个好文档，并不是那么容易写出来的。甚至可以说，大多数程序员写不出好文档，正如大多数人写不出好文章一样。
读者认真阅读。
读者理解正确。这很容易吗？不容易。
读者抓住重点。这也是很重要的。否则看了半天，应该记住的没记住，那也是白忙活。
一个文档要正确传递信息，实在不容易。要求写过多文档，其实是适得其反。所以吾在工作中，就对文档要求很少，主张“有用的文档”。
那些属于有用的文档？
说明性的文档，比如编译步骤、安装布署步骤。
关键性的程序流程图、模块图，配上简单的文字说明。
工作小结、事故总结。反对长篇大论，说明关键内容、工作思路等。
记录性的文档，比如几种做法的对比、不同设备的测试情况等等。
至于所谓的设计之类文档，从来不做要求。因为没有人看。
