背景

最近跟大家讨论了一下文档的问题，文档乱的问题真的是移动端开发的噩梦；

A：边写代码边给你写文档
B：写完了代码才给你写文档

C：你们都弱爆了，我们公司的接口文档靠口述加截图给你看源代码...
有时候什么接口还要问我，我反问他，他还说你不是移动端的吗？你肯定清楚啊（2333，自己写的接口自己不知道还特理直气壮）

我的工作环境

我们的 CTO（后台，公司里的比他小的都叫他 Yeming 哥哥） 文档写得非常漂亮，而且长得很帅，在我来的时候所有的接口文档都是他写，那时我们的研发团队不大但也不小，也有十几个，后台是4个，一向都是产品那边给我们过完需求他就开始给我们过接口文档，我当时很震惊，说：Yeming 哥哥，你们这么快就写好API 了吗？他说：没有，只是在过产品时就开始写文档，但是还没有开始 coding。我们产品会有好几次的 Review，CTO 会参与几轮，我们一般只参与第一轮。

开始我们的文档是以版本驱动，每个版本一个 Page，版本多了以后有时候要找以前的不好找，他们整理了一个很强大的文档，也是用人家的开源项目做的，放在 github作为一个单独的项目，预览时是这样的，这样我们可以直接在页面上 search，非常方便。

汇总文档

这个模板的开源地址是：https://github.com/tripit/slate

但是在开发新版本时要在那么多的接口里去找这个版本的文档也很麻烦，因为汇总文档是按模块排序的，所以除了这个汇总版本，每次的版本也有一个对应的page，按照以前的一样。

每个版本的 page

文档只是后台要写的？

有一次要开发一个新功能（一个逻辑还有点复杂的功能，但看似简单），我大致地想了一下，就单独开项目先写了，我写得差不多了，就开始往项目里整合，整合的时候有些问题，我就发现一个改一个，改到后来自己已经看不懂，而且还有很多 bug，这时项目已经很紧，离发布没多久了，我特别着急，但是觉得按照原来的改下去是肯定不行的，实现的机制就有问题，当晚我想了下到底应该怎么写，但是并没有开始。

第二天我按照前一天晚上的写法重新开始写，花了4个小时写好，测试完成一起花了6小时，这天是周五，我前面已经花了四天。除了一小块的 UI 写好的是可以用，逻辑部分几乎是重写。

那一次的版本我们发得很艰辛，版本完成后 Yeming 哥哥找我们谈话，我们跟他深刻反省了这次的错误，也讲述了原委。他说了这样一段话，令我受益匪浅，原话不记得了，大致意思如下

当你拿到一个需求时，不要急着去 coding，自己先思考准备如何实现，最好是自己先写一遍，不是写代码，而是写自己的实现方式，可以用文字，用伪代码都行，但千万不要自己埋头就开始 coding；
如果写到一半觉得有困难，也要停下来先想清楚，再继续。

我想很多人都有这样的感受，项目紧张，看着需求就开始写代码，写着写着越来越复杂，重新梳理又觉得来不及，浪费了时间，代码有时候没有那么重要，把思路理清楚，这是最重要的，或许不用说是写文档那么正式，就是写下自己的思路，无论以何种形式。

你并不是没有时间

很多开发人员以工作忙没有时间为由拒绝写文档，但是在我看来，这是一个开发人员的素养问题，写得好代码的人就肯定写得好文档，并不止是后台开发人员（对不起，标题只是为了吸引眼球），在进行工作交接时，对自己的项目的一些重点需要转述给自己的小伙伴时，都应该以文档驱动，即便你已经口头转述给ta，但请你也写一份文档，或者说，在你准备转述给他前，就应该把文档写好了。

Over

我想这应该是一个互联网公司最基本的要求，不以文档驱动会导致各种交流障碍，影响工作效率，因为这个浪费的时间足以让你去写一份优美的文档了，如果你 fight 了，他不理，老板不理，那此时不走，更待何时，说好的傲娇呢！