技术文档有用吗

技术文档有用吗

　

柳鲲鹏

2007-8-7

　

关键字：技术文档 作用

简介：虽然大家都认为技术文档应该有用，但事实告诉我们技术文档是没用的。别把写技术文档当作工作，浪费时间精力，有这种时间，不如要求员工多写一点注释，或者想办法训练一下员工。

　

　

　　在软件公司，最想做的，也是最受指责的，而且是从上到下异口同声的问题，说是技术文档缺乏，应该是没有疑问的。但大家看到的现象，是抱怨的本人也常常以工作忙为理由拒绝做出至少自己不抱怨的技术文档。更加奇怪的是，公司照常运行，产品照常出，工作照样交接。看到这种矛盾的现象，我们不禁要问：技术文档有用吗？

　　技术文档，简单的说，就是指跟代码相关的技术说明。技术文档的目的是什么？首先技术文档不是为作者自己看的，主要是为工作接手人看的。文档本身有什么情况？

　　文档写得详细，这种结果常常是比代码还长。这种结果有意义吗？

　　文档写得简要。这种文档马上就被人批评为太简单了没有意义。

　　文档有问题。一个是内容跟代码不一致，另外一个原因是没有及时更新。这种情况下，可以说有不如无。

　　

　　那工作接手人会看文档吗？如果接手人负责维护。大多数情况也就是解决几个BUG。此时通过DEBUG一路下来就差不多了（如果不幸是连DEBUG也不会的人那是公司的问题），搞不清楚原因加个特殊处理语句也解决。这种情况下文档自然无用。如果原有工作问题太多，要重新开发呢？这跟接手人能力相关：

　　接手人能力出色。这时他根本不会花时间研究文档浪费时间，而是直接动手从头再来。只有碰到个别极特殊的问题，他才可能参考一下老代码，这更用不上文档了。

　　接手人能力不出色。那么所谓重新开发就变成了搬代码。勤快的人还会趁机看一下代码把自己觉得不顺眼的地方改改（如果不幸改出错误就会老实了），有的干脆拷贝了事。这个时候，文档的作用又在哪里？

　　

　　尽管大家都认为技术文档有用，但在所有事实面前，技术文档是的确没有起到你想象中的作用。有人会说写文档有助于理清思路，难道写代码时会有人故意思路不清楚吗？花大量时间做这种无用功，实在没有意义。有这种时间，不如要求员工多写一点注释，或者想办法训练一下员工。

　　如果非要写一点文档，我建议软件公司别赶什么时髦，一个简要的流程图足矣，加上一些必要的说明；如果觉得不够，还可以把一些主要的DEBUG调用路径写一下来加上说明，让人一目了然。总之别把写技术文档当作工作，浪费时间精力，对工作不仅没有帮助，反而引起误解。