文档解决什么问题

📄今早组里的同事一直在问某个工具怎么用（内部的一个工具平台），这个工具对接到头条这边，目前只有三个员工有正式了解过，其他人是不知道的。工具的官方使用手册也着实写得差强人意，又长又臭😂，于是花了二十分钟写个科普文档从自己的认知角度来解释工具的作用，解决大家对工具的疑问。

想了想，到底什么时候需要来写文档呢？

写文档的目的，是为了解决某些需要反复沟通反复确认的问题，人脑是不可靠的，毕竟自己写的代码曾经理解过的东西，过一个月回来看可能就需要刻意回忆和理解了，文档正是以最简单明了的方式来唤醒人的记忆，或者直接并且不丢信息地传达思想。

给你一份文档你可以反复看，你可以过几天再看，反正你变着花式看都无所谓，有问题看文档，不用去打断别人的工作，这也是文档的好处。

不得不说，正是因为上面提到的原因，文档可能会发展成一种教条。凡是做出来的东西，都给写个文档出来，我不看具体的产出，我就看文档，我只需要通过文档去了解你的东西是什么……不仅仅是程序代码，文档虽然好使，但提供的信息毕竟有限，希望通过文档去获取到超越文档直至整个项目的信息量，是不存在的，这就是典型的本末倒置了，你总不能盼望我写一个程序，然后再写本书来解释程序的细节吧。

以前有个同事说过，文档只能反映项目当时的状态，它已经是历史。这句话是对的，文档往往较难随着项目一起迭代，如果人不参与进来，文档永远只能表达项目的历史状态，创作维护文档是需要成本的。工作经验教训了我，RD修改了代码，是不保证同步修改文档的，看文档不如看代码，看代码不如当面撕逼😂。同时文档又存在另外一个问题，就是它可能被一个不知情的人改坏了，或者有人悄悄把什么东西改了不通知大家，企图瞒天过海（功能有bug不符合文档描述，我把功能文档改过来，那这就不是bug而是feature了🤔）。

为了解决上面的问题，文档系统也开始进化了。出现文档历史快照功能，出现文档一经修改就群发通知的功能；开始提倡代码即文档，用代码生成文档；更新代码的时候应该同步更新文档等理念。这些东西都让文档越来越正规化，但是他们并没有增加文档的价值，只是在保持文档的价值不被各种骚操作抵消。

好像已经严重偏题了……

那什么时候需要写文档呢？

1. 项目前期沟通，将想法落地成可阅读可理解的文档，这样才具备多人可讨论性。
2. 项目稳定时，应该把稳定的部分抽取出来整理成文档减少沟通成本。
3. 需要大面积沟通同步时，传阅文档应该比开群会效果更好。
4. 文档可以提前梳理好各种疑问，有时候比口头更加全面一点。
5. 已经确认拍版的结论，最好让它变成文档成为证据。

文档永远是个灵活的东西，不要给它的使用场景设限……

但是切记文档与手册的区别，就像书籍也分精读书、略读书、工具书一样，文档如果过大过全失去重点，也就失去了它本身的意义，甚至没有人再愿意提前阅读它。