大多數程序員，都極度痛恨寫文檔。Coding是愉快的，而Write是痛苦的。有一部分原因，其實是要歸咎于程序員自身，以我的經驗，很多程序員往往會“艱于表達”，尤其是用“文字、圖表、PPT、Word”之類的Office Document來表達。當然，還有一部分原因，是由于很多項目開發實踐中，文檔的前后矛盾、形式主義、反復修改、歧義重重，常常讓程序員們抓狂。
?
UML是一個比較好的工具，但是，僅僅靠UML，是無法將項目的知識描述清楚的。也有不少項目組在引入了UML之后發現，文檔的工作量不但沒有減少，而是更多了。隨著項目的進展，需要維護的設計文檔數量，也更多了。也因此造成了更多的前后矛盾，形式主義，反復修改。
?
根本的痛苦，并不在于一開始寫一份文檔，而在于所有寫下的文檔，都必須跟隨項目的進展而隨之變化。當我們寫出來的文檔越多，需要被持續維護的文檔也就越多，需要反復檢查文檔間的可能存在的矛盾也就越多，所有扔出去的石頭，最后都會落回到自己頭上。
?
于是，還有不少項目組，將文檔工作與代碼工作截然分開，文檔就寫一次，用來應付上面的管理層，而代碼自管自的繼續開發。對于小型項目來說，這其實是一個不錯的權宜之計。但是一旦項目越來越龐大、復雜。所有的隱性的知識，都僅僅存在于程序員的腦子里，所有成文的東西，都可能是錯的，而真實的情況，卻隱藏在代碼之中。如果代碼質量再糟糕一些，后來維護的朋友，就遭遇火坑了。
?
文檔，寫還是不寫，這是一個問題！
?
還記得測試驅動開發嗎？為自己的每一個方法，每一個類，都寫出單元測試來。不但如此，更加徹底的做法是，在寫代碼之前，先寫測試用例。這樣才能保證不會忘記寫測試用例。更大的好處在于，這樣有助于思考、有助于獲得更加完善的設計，有助于寫出更加高質量的代碼，有助于安全的重構，有助于自動化的持續集成實踐。總之，是好得不能再好的一項開發實踐。
?
這一實踐之所以可行，就在于他將繁雜的集中的測試工作，分解為日常的，必須不斷進行的工作。當你每天都在寫測試用例，當你的每一個測試用例，都能夠與代碼完全對應時，壓力反而減輕了，工作量也更少了，更重要的，一些優良的習慣也因此被養成了。
?
在兩年前，我要開始一個全新的P2P網絡電視項目時，也在考慮關于文檔的問題。當時我發現了Open Source的WikiPedia。這是一個PHP的WIKI，最大的應用是維基百科全書。因此，這個項目的質量就絕對值得信賴。我就將它拿過來，作為我們項目文檔管理的工具。
?
用Wiki來管理項目文檔，基于以下一些考慮：
文檔是項目的知識，這些知識必須集中管理、容易獲取、人人可以編輯。
項目在生長，代碼在增加，文檔也必須能夠跟隨項目自然生長，強行劃分設計階段和開發階段，是不可取的。
Wiki不是傳統的項目文檔，而是一個應交流需要，可能隨時增刪改的知識庫。項目組的成員，遇到問題，就應該首先查看Wiki，如果這是Wiki中沒有，那么他應該找人詢問。而那個知道答案的人，如果他不想再今后不斷的回答同一問題，就應該把這個答案寫入Wiki，這就是Wiki條目增長的自然動力。
傳統文檔最大的問題在于浪費，而Wiki通過持續修改，按需提供的方式，保證了所有寫下的文字，一定有超過一個人需要讀它。
?
在Wikipedia的基礎上，我又做了一些增強，以更好的輔助項目的管理。
Include功能，增加include標簽，可以在一個條目中，引入其他條目的全文，而不是僅僅增加一個link。
文檔的層次結構，當項目的文檔條目逐漸增加，分門別類的條目，更加便于查找，也可以有效的避免條目重名的問題。
一個Click，就能夠創建新一個條目，用于填寫當天的工作安排。
相應的管理制度，也必須建立起來。
每日15分鐘文檔制度，基于“填寫當日工作”的功能，我規定每個項目組成員，每天要花三個5分鐘來寫文檔，早上的5分鐘，填寫當日工作計劃。中午的5分鐘填寫上午的工作情況，下班前的5分鐘，填寫下午的工作情況。這樣，每天的文檔工作相當輕松，但是文檔能夠保證持續的跟隨項目成長下去。更進一步的，這樣的制度，對于項目的進度控制，也很有幫助。
User Case條目驅動，所有分解出去的User Case，在分配到責任人之后，該責任人的第一項工作，就是在Wiki中寫下對于這個User Case的理解。隨后項目進展，也應該持續的維護這個條目。
同時進行Bug的管理，Bug也作為Wiki中的條目，以便于和其他條目項目引用。
每次Check In CVS時，必須寫注釋。這是更加細節的文檔，然后我還做了一個小程序，能夠自動的從CVSTrac中讀出當天Check In代碼的注釋。供每個人在寫當天文檔的時候引用。
總而言之，我對于項目文檔的看法，并不是非此即彼的極端主義者。在我看來，好的項目文檔管理政策，應該有助于集中團隊知識和智慧，同時不要讓程序員痛苦和反感。這樣才叫做有效的項目管理。仿造Martin Fowler的著名文獻《持續集成》，我給這篇Blog起這樣一個名字《軟件開發文檔的持續集成》，希望能夠引發更多的、更深入的思考。
posted on 2006-05-12 14:23
讀書、思考、生活 閱讀(28652)
評論(3) 編輯 收藏