文档！文档！

我曾听过有人这样说：

不喜欢写文档的人，往往是初入职场的新手，或者是能力一般。

说实在的，虽然说这句话不是我说的，但是把这句话放在这里，着实也显得非常冒犯。毕竟，关心「为何要写文档」这个话题的人中，不喜欢写文档的人很可能会占多数（我这是在找打的节奏么）。

不喜欢写文档的朋友，你们水平如何，小弟实在不敢妄自评判。我也确实遇到过许多不喜欢写文档的技术大牛。我们抛开人身攻击的范畴，单单对于文档的意义，与大家进行一次深入的讨论，是我这篇文档想要达到的一个主要目的。

虽然，这里提到的文档，主要是指软件工程中对应的开发文档，但是这里的讨论，其实对各种产品文档，甚至用户说明书，都同样适用。

让你的代码保值甚至增值

如果你写代码的目的，仅仅是为了做个技能练习，或者是为了验证某个技术猜想，属于写完就扔的情形，你大可不必写那些讨厌的文档。但是，如果你是认真的，想让你的代码被更多的人阅读，使用，甚至为优化这段代码做贡献，那么，你确实有必要好好写一下配套文档。为什么呢？

• 你的代码被人用的越多，它才会越有价值；
• 如果你没有说明你的代码是干什么用的，那么很少会有人找到你；
• 介绍了你的代码的作用和功能，但是没有交代使用方法，大家可能仍然不会使用你的代码；
• 你介绍了代码的大体功能，以及如何使用，但是说的却不够清楚，那你的第一批客户很可能由于没有足够的精力和耐心去细致分析你的代码，最终仍然很少有人用你的代码；
• 你的代码可以用，但是需要稍微修改一下符合你的用户的个人需求，但是用户发现你的代码没有文档，阅读修改起来吃力，用户很可能就会放弃对它的深入贡献和维护；
• 一段代码一旦没人使用，无论之前你为之付出了多少努力，它仍难逃死亡的命运，最终被人遗忘。

所以，从对你的作品负责的角度，请为它配上文档。

支撑你的系统迭代

对于想把代码写好，产品做好的有志青年，你不可能不明白「迭代」的重要性。在操练一门技能，如何快速逆天？这篇文章中，专门对「迭代环境」这个话题进行了讨论。

一个合格的文档，里面会记录我们在做产品设计，方案选型，方案论证等各个环节的必要信息。当我们的代码，系统或产品在发展过程中遇到阻力，困难或瓶颈时，文档就派上用场了。通过我们的设计文档，我们可以重新思考审视一下当前的设计方案，并找出优化方案来。

这个时候，如果你没有文档，那很可能情景就是这样的了：

年轻人：哇，我们这个系统好讨厌啊，怎么会有这么弱智的设计！！！
老油条: 额，我也不知道，虽然我来公司比你早，但是，貌似一开始就是这样设计的，没人知道为什么…… 其实，我都习惯了……
年轻人: 我们怎么可以这样啊，我们要有勇气，优化改革我们的方案啊！
老油条: 确实有必要改一改了，不过据我经验，类似的情形，我们公司往往越改越崩溃啊……

遇到上面的情形，对当前的系统进行优化，当然是很有必要的。但是如果没有文档支持，他们的未来，可能真的会被老油条预言中：

• 他们选择了一个已经被验证无效，但是却未被文档记录的技术方案，从而浪费了大量资源；
• 由于没有完备的文档对系统的所有需求点进行完备描述，很可能他们解决的眼前的问题，却导致某些已有的功能失效，引来客户或者相关人员的投诉；
• 当前的技术方案，有可能是为了缓和某个痛点的权宜之计，贸然提出新方案，可能使问题被进一步激化；

这样的情况真是糟糕：团队的成果无法继承，并持续的工作在低效循环中。

自动化工作流

我们个人，或者团队中，经常会有一些工作，需要我们非常小心：

• 工作必须按照某个顺序流程进行；
• 流程顺序错误，或者缺失流程，会导致工作失败；
• 过程繁琐，交流成本高，且人工操作起来容易出错，

像这样性质的工作，如果没有一个不断完备优化的文档对工作细节进行记录，那么我们就很难把控工作质量。这样的工作，出现失误，并不能把责任全部归给当事人，因为这类工作本身就很反人类。我们更需要找出合理可靠的解决方案，来防止人类犯错误。

所以，最笨的办法，就是把工作流程一步一步写下来，形成文档，并不断完善；有了完善的文档，如果条件允许，就可以将工序交给机器，实现工作的自动化。

节约团队沟通成本

如果在和你的客户确认需求时，你的客户没有给出一个需求说明书，那么你真的需要自己写一份，并拿给他确认。如果他坚持说，「不不不，我们没那么多时间写文档，先开干吧」，那么我劝你，出于规避风险，同时为客户负责的方面考虑，尽早委婉的拒绝与他合作吧。

即使在团队内部，如果有可能的话，书面的交流总会比口头的交流来的更有效，特别的你的团队人数比较庞大。

书面的沟通，就是文档。书面的沟通，除了有表达更加清楚，不存在传递失真的问题之外，更重要的有点是，能够以最低的成本，对待沟通的信息进行不断完善。

即使与你有交集的同事只有两三个，面对两种交流方案：一种交是，每个信息都要重复两三遍地跟他们解释；另一种方案是写一个书面的说明，在需要修改时就基于之前的进行补充，标注好版本号，并发给他们，即使之后突然又多出十几个朋友需要你跟他门做同样的交流，你的压力也不会变得很大。稍微想一下，你必然能体会到文档的甜头。

让你和你的代码更加优秀

不得不承认，人有一个不算是缺点的缺点：喜欢靠直觉做决定，而不是靠深入思考。

当你有一个点子，你是先写文档还是先打开你的IDE开始编码？如果你是选择后者，那么，也许你很快就能体会到，往往想着容易做着难。做着做着，发现遇到困难，走不下去了。瞬间一股强烈的沮丧感迎面而来。长此以往，浪费了时间不说，心理素质稍差的，可能自信心都会遭到影响甚至和打击。

说到这，你也许就能明白了，写文档本身也是进行系统设计的必经步骤。

写文档，不但能从设计阶段就启动产品的打磨，同时也是在磨练你个人严谨求实的工作习惯和行事作风。

话已至此

所以，你打算如何编写你的文档？