本博客所有內(nèi)容采用 Creative Commons Licenses 許可使用. 引用本內(nèi)容時(shí)，請(qǐng)保留 朱濤, 出處 ，并且 非商業(yè) .
點(diǎn)擊 訂閱 來(lái)訂閱本博客.(推薦使用 google reader, 如果你的瀏覽器不支持直接訂閱,請(qǐng)直接在 google reader 中手動(dòng)添加).
點(diǎn)擊 下載pdf閱讀 (如果瀏覽器不支持直接打開,請(qǐng)點(diǎn)擊右鍵另存)
本文主要是結(jié)合作者的項(xiàng)目實(shí)踐來(lái)說(shuō)明文檔對(duì)于一個(gè)團(tuán)隊(duì)開發(fā)的重要性, 以及在提高效率節(jié)省時(shí)間方面的意義, 并且指出如何在實(shí)踐開發(fā)中寫文檔與維護(hù)文檔.
請(qǐng)先思考下面幾個(gè)問(wèn)題:
如果你思考這些問(wèn)題時(shí),只是不住地在搖頭, 那么, 是你為自己的項(xiàng)目寫文檔或者要求團(tuán)隊(duì)成員建立文檔系統(tǒng)的時(shí)候了.
其實(shí)原因很簡(jiǎn)單, 1) 為新手提供一個(gè)快速入門的路徑 2)為自己節(jié)省大量的寶貴時(shí)間 3)為項(xiàng)目贏得更多的開發(fā)時(shí)間 4)在一個(gè)high-level的層次 提供項(xiàng)目的一個(gè)審視角度(code是low-level)
如果你還在耐心而細(xì)致地為自己團(tuán)隊(duì)新加入的成員解釋開發(fā)環(huán)境如何配置, 整個(gè)開發(fā)框架, 或者整個(gè)團(tuán)隊(duì)的構(gòu)成等, 我在對(duì)你的 耐心保持欽佩的同時(shí),也在心里責(zé)備你的低效(如果我是你的leader, 我可不希望你把時(shí)間老是花在教導(dǎo)新手上).
相比于編碼和開發(fā), 那種相應(yīng)而生的結(jié)果會(huì)給你不斷帶來(lái)一些欣喜和成就感, 而寫文檔, 很枯燥, 它只是一些文字的堆積,不會(huì) 讓項(xiàng)目進(jìn)展向前, 也不會(huì)讓你在自己負(fù)責(zé)模塊中去掉一條todo. 這就是成就感的問(wèn)題.
更讓人煩惱的是, 你的代碼可能會(huì)不斷重構(gòu), 框架也會(huì)不斷修改, 代碼的注釋你很自然地隨之更新,而文檔你又懶得去動(dòng)了, 但是不動(dòng), 又不能反映最新的代碼和框架, 不僅不能幫助閱讀文檔的同事,更甚會(huì)讓他們"誤入歧途", 于是你無(wú)奈地去更新了文檔, 在更新中 你發(fā)誓不再寫這些文檔了. 這就是維護(hù)的問(wèn)題.
或者更偏激地說(shuō),有部分的程序員更是不樂(lè)意將框架或者自己的經(jīng)驗(yàn)寫成文檔(我想這是少數(shù)的), 因?yàn)樗P算自己一路走過(guò)的艱辛, 到后來(lái)就認(rèn)為這種無(wú)文檔死磕代碼的過(guò)程是必須的, 也就心安理得地去看著新手在荊棘中前行. 這是心態(tài)的問(wèn)題.
還有一部分程序員, 他們認(rèn)為自己是沒有能力寫文檔,或者說(shuō)是沒有到寫文檔的水平, 雖然自己會(huì)用現(xiàn)在的框架,但是又弄不清楚, 它的實(shí)現(xiàn),及其相應(yīng)的數(shù)據(jù)交互和設(shè)計(jì)理念等. 他怕寫出的文檔會(huì)誤導(dǎo)別人,怕"出洋相". 這就是思路的問(wèn)題.
等等,可能還有其它的原因.
那么,我來(lái)逐條地分析你不寫文檔是不對(duì)的.
當(dāng)然,大道理誰(shuí)都會(huì)說(shuō),關(guān)鍵行動(dòng)還在于你自己.
回到一個(gè)比較關(guān)鍵的問(wèn)題, 就是究竟該如何寫文檔, 哪些應(yīng)該寫,哪些不應(yīng)該寫.
在寫文檔前,你得思考,要寫哪些內(nèi)容, 我總結(jié)如下:
項(xiàng)目中關(guān)鍵處理邏輯
- 使用的框架
- 整個(gè)處理過(guò)程(譬如點(diǎn)擊一個(gè)link或者button后,后續(xù)的完整處理流程和交互邏輯)
規(guī)范性內(nèi)容(如編碼規(guī)范,文檔規(guī)范, 注釋規(guī)范等等)
知識(shí)性內(nèi)容(如某個(gè)工具的使用方法, 某個(gè)插件如何提高開發(fā)效率等)
經(jīng)驗(yàn)性東西(如一些最佳實(shí)踐, sql如何寫, 如何保證代碼的可復(fù)用性等)
教程性內(nèi)容(如如何讓一個(gè)新手使用當(dāng)前的框架寫出一個(gè)功能等,如何讓他快速入門)
FAQ類似的內(nèi)容(當(dāng)你被同事或者客戶同一個(gè)問(wèn)題問(wèn)了超過(guò)3遍時(shí),你就應(yīng)該寫出文檔來(lái), 來(lái)避免再次被占用這寶貴的程序員時(shí)間)
當(dāng)然上面提到的都是開發(fā)相關(guān)的文檔, 也是我們每個(gè)程序員可能要寫的. 還有幾類文檔, 如需求文檔, 開發(fā)文檔, 測(cè)試文檔, 用戶文檔等, 也可能需要程序員參與.
除此而外,另一大類,就是代碼的API, 這類文檔最好的處理方式是自動(dòng)化, 如 doxygen, epydoc 等一系列工具. 使用這樣的工具, 可以免去重新寫API的文檔,只需要自動(dòng)生成即可, 而后續(xù)如果代碼和注釋有更動(dòng),也只需要重新生成即可.
解決了寫哪些內(nèi)容, 我們來(lái)看,如何去與文檔, 如何去維護(hù)文檔.
這里有個(gè)參考: How to make documents evolve?
我經(jīng)歷過(guò)的團(tuán)隊(duì), 有不寫文檔的, 有寫文檔但是經(jīng)常會(huì)過(guò)時(shí)的, 也有維護(hù)較好的. 根據(jù)我個(gè)人的經(jīng)驗(yàn),我的建議是:
使用一個(gè)良好組織的wiki來(lái)作為文檔管理系統(tǒng), 對(duì)于項(xiàng)目中的文檔中及時(shí)更新, 保證是準(zhǔn)確和正確的.
當(dāng)然,如果你不想去維護(hù)一個(gè)文檔系統(tǒng), 那么寧可不要文檔, 因?yàn)?nbsp;錯(cuò)誤的文檔還不如沒有文檔.
那么文檔放在哪里合適呢?
個(gè)人建議是與代碼一起納入版本控制系統(tǒng),如我在 你使用源碼管理工具嗎? 中推薦的 bitbucket, 中集成有wiki. 這樣維護(hù)和更新起來(lái)都會(huì)比較方便.
文檔是一個(gè)公司實(shí)力的體現(xiàn),也是管理者素質(zhì)和能力的體現(xiàn), 它對(duì)于開發(fā)者是極大的財(cái)富.所以維護(hù)一個(gè)良好組織的文檔, 不僅能夠在開發(fā)中讓你獲益無(wú)數(shù), 而且在提高成員對(duì)團(tuán)隊(duì)的認(rèn)可度,對(duì)公司的忠誠(chéng)度等方面也會(huì)有很大的提升.
如果你們團(tuán)隊(duì)還沒有文檔,現(xiàn)在就開始寫吧.
還記得自己曾經(jīng)在加入一個(gè)團(tuán)隊(duì)時(shí), 得到的只是一個(gè)svn賬號(hào), 一個(gè)任務(wù)說(shuō)明, 然后就是deadline. 而且我們是遠(yuǎn)程的, 沒有更多的交流機(jī)會(huì). 當(dāng)時(shí)那接下來(lái)的幾天,真是暗無(wú)天日, 我生生地在讀代碼, 做夢(mèng)企盼天上能掉下來(lái)一個(gè)文檔. 經(jīng)過(guò)艱苦卓絕的努力, 一周后,還是弄清楚了整個(gè)框架和思路, 我便寫了一個(gè)文檔, 不希望后面的同事也和我經(jīng)驗(yàn)同樣的苦痛與無(wú)助.
聯(lián)系客服
