背景
最近跟大家討論了一下文檔的問題牍疏，文檔亂的問題真的是移動(dòng)端開發(fā)的噩夢(mèng)蠢笋；
A：邊寫代碼邊給你寫文檔
B：寫完了代碼才給你寫文檔
C：你們都弱爆了，我們公司的接口文檔靠口述加截圖給你看源代碼...
有時(shí)候什么接口還要問我鳞陨，我反問他昨寞，他還說你不是移動(dòng)端的嗎？你肯定清楚跋寐恕（2333援岩，自己寫的接口自己不知道還特理直氣壯）
我的工作環(huán)境
我們的 CTO（后臺(tái)，公司里的比他小的都叫他 Yeming 哥哥） 文檔寫得非常漂亮掏导，而且長(zhǎng)得很帥享怀，在我來的時(shí)候所有的接口文檔都是他寫，那時(shí)我們的研發(fā)團(tuán)隊(duì)不大但也不小趟咆，也有十幾個(gè)添瓷，后臺(tái)是4個(gè)，一向都是產(chǎn)品那邊給我們過完需求他就開始給我們過接口文檔值纱，我當(dāng)時(shí)很震驚鳞贷，說：Yeming 哥哥，你們這么快就寫好API 了嗎虐唠？他說：沒有搀愧，只是在過產(chǎn)品時(shí)就開始寫文檔，但是還沒有開始 coding疆偿。我們產(chǎn)品會(huì)有好幾次的 Review咱筛，CTO 會(huì)參與幾輪，我們一般只參與第一輪杆故。
開始我們的文檔是以版本驅(qū)動(dòng)迅箩，每個(gè)版本一個(gè) Page，版本多了以后有時(shí)候要找以前的不好找反番，他們整理了一個(gè)很強(qiáng)大的文檔沙热，也是用人家的開源項(xiàng)目做的叉钥，放在 github作為一個(gè)單獨(dú)的項(xiàng)目罢缸，預(yù)覽時(shí)是這樣的，這樣我們可以直接在頁面上 search投队，非常方便枫疆。
這個(gè)模板的開源地址是：https://github.com/tripit/slate
但是在開發(fā)新版本時(shí)要在那么多的接口里去找這個(gè)版本的文檔也很麻煩，因?yàn)?strong>匯總文檔是按模塊排序的敷鸦，所以除了這個(gè)匯總版本息楔，每次的版本也有一個(gè)對(duì)應(yīng)的page寝贡，按照以前的一樣。
文檔只是后臺(tái)要寫的值依？
有一次要開發(fā)一個(gè)新功能（一個(gè)邏輯還有點(diǎn)復(fù)雜的功能圃泡，但看似簡(jiǎn)單），我大致地想了一下愿险，就單獨(dú)開項(xiàng)目先寫了颇蜡，我寫得差不多了，就開始往項(xiàng)目里整合辆亏，整合的時(shí)候有些問題风秤，我就發(fā)現(xiàn)一個(gè)改一個(gè)，改到后來自己已經(jīng)看不懂扮叨，而且還有很多 bug缤弦，這時(shí)項(xiàng)目已經(jīng)很緊，離發(fā)布沒多久了彻磁，我特別著急碍沐，但是覺得按照原來的改下去是肯定不行的，實(shí)現(xiàn)的機(jī)制就有問題衷蜓，當(dāng)晚我想了下到底應(yīng)該怎么寫抢韭，但是并沒有開始。
第二天我按照前一天晚上的寫法重新開始寫恍箭，花了4個(gè)小時(shí)寫好刻恭，測(cè)試完成一起花了6小時(shí)，這天是周五扯夭，我前面已經(jīng)花了四天鳍贾。除了一小塊的 UI 寫好的是可以用，邏輯部分幾乎是重寫交洗。
那一次的版本我們發(fā)得很艱辛骑科，版本完成后 Yeming 哥哥找我們談話，我們跟他深刻反省了這次的錯(cuò)誤构拳，也講述了原委咆爽。他說了這樣一段話，令我受益匪淺置森，原話不記得了斗埂，大致意思如下
當(dāng)你拿到一個(gè)需求時(shí)，不要急著去 coding凫海，自己先思考準(zhǔn)備如何實(shí)現(xiàn)呛凶，最好是自己先寫一遍，不是寫代碼行贪，而是寫自己的實(shí)現(xiàn)方式漾稀，可以用文字模闲，用偽代碼都行，但千萬不要自己埋頭就開始 coding崭捍；
如果寫到一半覺得有困難尸折，也要停下來先想清楚，再繼續(xù)殷蛇。
我想很多人都有這樣的感受翁授，項(xiàng)目緊張，看著需求就開始寫代碼晾咪，寫著寫著越來越復(fù)雜收擦，重新梳理又覺得來不及，浪費(fèi)了時(shí)間谍倦，代碼有時(shí)候沒有那么重要塞赂，把思路理清楚，這是最重要的昼蛀，或許不用說是寫文檔那么正式宴猾，就是寫下自己的思路，無論以何種形式叼旋。
你并不是沒有時(shí)間
很多開發(fā)人員以工作忙沒有時(shí)間為由拒絕寫文檔仇哆，但是在我看來，這是一個(gè)開發(fā)人員的素養(yǎng)問題夫植，寫得好代碼的人就肯定寫得好文檔讹剔，并不止是后臺(tái)開發(fā)人員（對(duì)不起，標(biāo)題只是為了吸引眼球）详民，在進(jìn)行工作交接時(shí)延欠，對(duì)自己的項(xiàng)目的一些重點(diǎn)需要轉(zhuǎn)述給自己的小伙伴時(shí)，都應(yīng)該以文檔驅(qū)動(dòng)沈跨，即便你已經(jīng)口頭轉(zhuǎn)述給ta由捎，但請(qǐng)你也寫一份文檔，或者說饿凛，在你準(zhǔn)備轉(zhuǎn)述給他前狞玛，就應(yīng)該把文檔寫好了。
Over
我想這應(yīng)該是一個(gè)互聯(lián)網(wǎng)公司最基本的要求涧窒，不以文檔驅(qū)動(dòng)會(huì)導(dǎo)致各種交流障礙心肪，影響工作效率，因?yàn)檫@個(gè)浪費(fèi)的時(shí)間足以讓你去寫一份優(yōu)美的文檔了杀狡，如果你 fight 了蒙畴，他不理贰镣，老板不理呜象，那此時(shí)不走膳凝，更待何時(shí)，說好的傲嬌呢恭陡！
