摘要

本文主要是結(jié)合作者的項目實踐來說明文檔對于一個團隊開發(fā)的重要性, 以及在提高效率節(jié)省時間方面的意義, 并且指出如何在實踐開發(fā)中寫文檔與維護文檔.

引入

請先思考下面幾個問題:

1. 如果你是剛加入一個項目組的新手,你能夠看到你們項目的相關(guān)文檔嗎?你希望看到嗎?
2. 如果你是一個架構(gòu)師,或者高級程序員, 你經(jīng)常會被其他同事詢問相關(guān)的架構(gòu)問題嗎?你會千百遍地回答同一個問題嗎?
3. 你是如何寫文檔的呢? 你為哪些內(nèi)容些文檔呢? 你是如何管理文檔的呢? 你如何保證文檔與代碼同步呢?

如果你思考這些問題時,只是不住地在搖頭, 那么, 是你為自己的項目寫文檔或者要求團隊成員建立文檔系統(tǒng)的時候了.

為什么要寫文檔

其實原因很簡單, 1) 為新手提供一個快速入門的路徑 2)為自己節(jié)省大量的寶貴時間 3)為項目贏得更多的開發(fā)時間 4)在一個high-level的層次 提供項目的一個審視角度(code是low-level)

如果你還在耐心而細致地為自己團隊新加入的成員解釋開發(fā)環(huán)境如何配置, 整個開發(fā)框架, 或者整個團隊的構(gòu)成等, 我在對你的 耐心保持欽佩的同時,也在心里責備你的低效(如果我是你的leader, 我可不希望你把時間老是花在教導新手上).

為什么大多數(shù)程序員都不喜歡寫文檔

相比于編碼和開發(fā), 那種相應而生的結(jié)果會給你不斷帶來一些欣喜和成就感, 而寫文檔, 很枯燥, 它只是一些文字的堆積,不會 讓項目進展向前, 也不會讓你在自己負責模塊中去掉一條todo. 這就是成就感的問題.

更讓人煩惱的是, 你的代碼可能會不斷重構(gòu), 框架也會不斷修改, 代碼的注釋你很自然地隨之更新,而文檔你又懶得去動了, 但是不動, 又不能反映最新的代碼和框架, 不僅不能幫助閱讀文檔的同事,更甚會讓他們"誤入歧途", 于是你無奈地去更新了文檔, 在更新中 你發(fā)誓不再寫這些文檔了. 這就是維護的問題.

或者更偏激地說,有部分的程序員更是不樂意將框架或者自己的經(jīng)驗寫成文檔(我想這是少數(shù)的), 因為他盤算自己一路走過的艱辛, 到后來就認為這種無文檔死磕代碼的過程是必須的, 也就心安理得地去看著新手在荊棘中前行. 這是心態(tài)的問題.

還有一部分程序員, 他們認為自己是沒有能力寫文檔,或者說是沒有到寫文檔的水平, 雖然自己會用現(xiàn)在的框架,但是又弄不清楚, 它的實現(xiàn),及其相應的數(shù)據(jù)交互和設(shè)計理念等. 他怕寫出的文檔會誤導別人,怕"出洋相". 這就是思路的問題.

等等,可能還有其它的原因.

為什么我們應該去寫文檔呢

那么,我來逐條地分析你不寫文檔是不對的.

1. 成就感: 個人認為, 一天寫的code越少, 思考的時間, 寫文檔的時間越多, 正是說明了你能力的提升, 說明了你心中有big picture, 而 不再只拘泥于去實現(xiàn)一個feature, 一個功能. 思考是為了寫出更好的代碼, 寫文檔是為了更好支持后續(xù)的代碼維護和對新手的關(guān)懷. 你的新同事當看到你寫的文檔時,他會打心眼里感激你的.你的老板在看到你條理清楚的文檔時, 他會考慮提拔你的. 想必你也知道項目經(jīng)理的 工作不再專注于代碼,而是文檔(需求文檔,開發(fā)文檔等). 所以,在寫文檔時,你要自信,你更要覺得有更高的成就感.
2. 維護: 文檔的更新肯定是滯后于代碼的更新的, 所以要保持文檔的正確和準確,就必須有一定的機制來保證文檔也是最新的. 經(jīng)過實踐證明,使用 wiki這樣的系統(tǒng)來維護文檔是比較合適而且高效, 因為:
   • wiki本身的一個特點就是 不斷變化更新的 , 所以其他同事會知道, 這些文檔會不斷更新,我要不斷tracking
   • wiki內(nèi)置的版本控制,也會很方便文檔的撰寫與分享
   • wiki本身的協(xié)作機制,也會讓維護起來更加方便(想想wikipedia,有哪篇文章是一個人一次性完成的)
3. 心態(tài): 分享不只是一種行為而且是一種精神, 當你看到本篇博客時, 我正在分享, 當你看完后寫一個留言時,你也在分享. 分享是互聯(lián)網(wǎng)的基石, 也是知識價值最大化的體現(xiàn).如果你還想或者以為自己的過去的艱辛也希望別人同樣經(jīng)歷, 我想我不會看好你的未來,我也不希望和你成為朋友, 而這些行為 本身也不能讓你獲益多少.保守而封閉的思路,則會 影響到你所能達到的level. 我們在努力工作,努力學習的每一天都是希望我們自己以后的子女不再這么辛苦, 那何嘗不可以將"子女"擴大到 每一個人呢?將知識分享給朋友, 分享給他人, 你也會得到別人的認可與支持, 當然他們也會回饋給你他們的心得與體會. 分享的路上你并不孤單.
4. 思路: 首先認為自己沒有能力或者水平寫文檔的程序員都是有著錯誤的思路, 因為 沒有人能夠保證他寫的都是正確的, 即使是 Donald Knuth 大牛. 你寫出的東西, 你的同事看了, 在獲益的同時,倘若發(fā)現(xiàn)的問題,他并不會責備你, 而會懷著感激與討論的心態(tài)來與你交流,最終你也許就糾正了 自己的錯誤, 從而成長起來. 如果你不去分享,也許你一輩子都不會明白,"哦,原來應該是這樣". 寫出自己的思路, 寫出自己的認識, 與別人分享,幫助別人, 也提高自己.

當然,大道理誰都會說,關(guān)鍵行動還在于你自己.

回到一個比較關(guān)鍵的問題, 就是究竟該如何寫文檔, 哪些應該寫,哪些不應該寫.

如何寫文檔

在寫文檔前,你得思考,要寫哪些內(nèi)容, 我總結(jié)如下:

1. 項目中關(guān)鍵處理邏輯

   • 使用的框架
   • 整個處理過程(譬如點擊一個link或者button后,后續(xù)的完整處理流程和交互邏輯)

2. 規(guī)范性內(nèi)容(如編碼規(guī)范,文檔規(guī)范, 注釋規(guī)范等等)

3. 知識性內(nèi)容(如某個工具的使用方法, 某個插件如何提高開發(fā)效率等)

4. 經(jīng)驗性東西(如一些最佳實踐, sql如何寫, 如何保證代碼的可復用性等)

5. 教程性內(nèi)容(如如何讓一個新手使用當前的框架寫出一個功能等,如何讓他快速入門)

6. FAQ類似的內(nèi)容(當你被同事或者客戶同一個問題問了超過3遍時,你就應該寫出文檔來, 來避免再次被占用這寶貴的程序員時間)

當然上面提到的都是開發(fā)相關(guān)的文檔, 也是我們每個程序員可能要寫的. 還有幾類文檔, 如需求文檔, 開發(fā)文檔, 測試文檔, 用戶文檔等, 也可能需要程序員參與.

除此而外,另一大類,就是代碼的API, 這類文檔最好的處理方式是自動化, 如 doxygen, epydoc 等一系列工具. 使用這樣的工具, 可以免去重新寫API的文檔,只需要自動生成即可, 而后續(xù)如果代碼和注釋有更動,也只需要重新生成即可.

解決了寫哪些內(nèi)容, 我們來看,如何去與文檔, 如何去維護文檔.

這里有個參考: How to make documents evolve?

我經(jīng)歷過的團隊, 有不寫文檔的, 有寫文檔但是經(jīng)常會過時的, 也有維護較好的. 根據(jù)我個人的經(jīng)驗,我的建議是:

使用一個良好組織的wiki來作為文檔管理系統(tǒng), 對于項目中的文檔中及時更新, 保證是準確和正確的.

當然,如果你不想去維護一個文檔系統(tǒng), 那么寧可不要文檔, 因為 錯誤的文檔還不如沒有文檔.

那么文檔放在哪里合適呢?

個人建議是與代碼一起納入版本控制系統(tǒng),如我在 你使用源碼管理工具嗎? 中推薦的 bitbucket, 中集成有wiki. 這樣維護和更新起來都會比較方便.

結(jié)論

文檔是一個公司實力的體現(xiàn),也是管理者素質(zhì)和能力的體現(xiàn), 它對于開發(fā)者是極大的財富.所以維護一個良好組織的文檔, 不僅能夠在開發(fā)中讓你獲益無數(shù), 而且在提高成員對團隊的認可度,對公司的忠誠度等方面也會有很大的提升.

如果你們團隊還沒有文檔,現(xiàn)在就開始寫吧.

后記

還記得自己曾經(jīng)在加入一個團隊時, 得到的只是一個svn賬號, 一個任務說明, 然后就是deadline. 而且我們是遠程的, 沒有更多的交流機會. 當時那接下來的幾天,真是暗無天日, 我生生地在讀代碼, 做夢企盼天上能掉下來一個文檔. 經(jīng)過艱苦卓絕的努力, 一周后,還是弄清楚了整個框架和思路, 我便寫了一個文檔, 不希望后面的同事也和我經(jīng)驗同樣的苦痛與無助.

參考資料

1. How to make documents evolve?
2. Donald Knuth

本文的rst源碼