寫文檔的困惑
寫文檔不像寫代碼，它沒有明確的好與壞，更沒有明顯的正確與不正確。也正因為此，對於寫慣了代碼的程序員來說，寫文檔是無比痛苦的，完全找不着北。
寫短了，人家說沒寫清楚，太不詳細；寫得長了，人家說太瑣碎，那么長，哪有精力看。
領導說，“這個問題簡單，兩三頁隨便描述一下就行了。”你若真是只寫個兩三頁，百分之百挨批。
又要言簡意賅，又要表述詳盡。這比寫代碼要費勁多了。
我們寫代碼時，講什么重構呀重構，有幾個人寫完代碼重構的？沒幾個吧。有哪一個寫完程序重構個十來回的？亘古少有吧。而寫文檔，隨便一個文檔，被重構個十來回、幾十回，甚至推倒重來個幾回都很正常。
寫代碼與寫文檔，完全是兩個境界。要不怎么說，寫代碼的工資，不如寫文檔的；寫文檔的工資不如寫PPT的。PPT相對於文檔更加精煉，所以寫起來更困難。
看文檔的困惑
商務經理寫的立項說明，研發經理看不明白；項目經理寫的需求分析，開發人員看不明白，包括我自己寫的文檔也有別人看不懂的時候，呵呵。
當然了，我這么說，會有人很不服氣，“哪里不明白？你說哪里不明白？哪不明白你問我，我給你講。”
尤其常見的是，當新員工拿到開發資料后，看不懂，只好問老員工，老員工不耐煩，“文檔上不是寫的很清楚嗎？找不着？這里，這里，不是嗎？……看不懂？你自己看不懂怨誰？”新員工不吭聲了，郁悶到一定程度就悄悄辭職了，剩下牛逼哄哄的老員工發牢騷。
我也坦誠，大多數項目文檔，我都沒有從開頭看到結尾過，哪怕兩三頁的文檔，都是跳讀。其實不僅是項目文檔，除了小 說，幾乎所有的書籍、資料我都是跳讀，瀏覽一下大概意思就完事兒了，具體到某個問題時，再着重閱讀相關章節。問題在於，重點問題往往沒有重點表達。
一般閱讀文檔都會通過文檔結構圖來查閱，那個文檔結構圖其實就是文檔的骨架。一個完整的文檔自然是從頭到腳都有的，但我們並不會從頭看到腳。就像我們看一個人一樣，如果對方胳膊腿少一樣我們都會感到吃驚，但我們面對對方時，卻不會從頭到看到腳，如果真這樣，實在太不禮貌了。我們只需關注重點。
文檔模板的編寫
單純依靠作者的文字能力、創作能力寫出好的文檔是不靠譜的，畢竟大家不是專業寫手。基本思路還是“套模板”，軟件工程有國標的文檔模板，也有ISO的文檔模板，也有CMMI的文檔模板，可是任何一個模板拿過來，都不好往上套，實在讓人郁悶。究其原因，那些模板只是一個殼，沒有任何編寫指導，編不出來東西。
我想，好的文檔模板應該遵循如下原則：
可選、可刪、可填、可編；
能夠讓作者打勾選擇的內容項，盡量打勾選擇，例如文檔保密級別，可以提供三項供選擇“□普通 □保密 □機密”而不是讓作者去填寫，他有可能不知道該填什么；
其次是“可刪”，即內容可以刪減，模板中盡可能提供一些常用的文檔段落，例如，文檔的目標讀者，可以在模板中列舉出盡可能多的目標讀者，如“目標讀者包括：總經理，技術總監，項目經理，客戶經理，需求分析人員，系統架構師，項目建設方負責人”；作者在編寫文檔時根據需要刪除多余的，如果讓作者增加內容，他可能不太容易想的周全。
再其次是“可填”，前文說過，文檔往往重點內容沒有重點表達，甚至會遺漏關鍵問題的描述，原因也不是作者不想去寫清楚，往往是事情多，一時思慮不周造成的。那么在模板中盡可能把需要描述的內容列舉出來，例如，項目概述部分，涉及項目目標、功能范圍、工期約束、承建單位、項目規模、驗收方式等等，在模板中逐個列舉，供作者填寫，這樣就不會遺漏內容項。
最后，就是“可編”了，畢竟文檔中還有很多內容需要作者根據具體的項目情況需要編寫，這個工作有一定的創造性，也最讓人感覺困難，建議編寫時參考以往的文檔，比葫蘆畫瓢是最基礎技法。
大家可能會想，有這樣的模板真是太好了，可這樣的文檔模板容易做出來嗎？的確不太容易，僅靠項目經理來組織編寫文檔模板是完全不夠的，如果公司有項目管理部門，或項目管理委員會（PMO）出面來處理這個事情，會好一些。
文檔內容的編寫
文檔編寫比較麻煩，我在這里說一下我的編寫心得。
在文檔的編寫過程中，我用的最多的軟件並不是Word，而MindManager與OneNote，Word僅用於最后的文檔編排與修訂。
MindManager顧名思義是思維管理的工具，可以用它畫思維導圖、結構圖等，還可以進行頭腦風暴。當我要開始編寫某個東西時，我一般會用MindManager的頭腦風暴功能，把自己能想到的、相關的所有內容，都敲出來，然后把這些內容進行歸納、增刪、編排，很快一個像八爪魚一樣的思維導圖就出來了，這其實就是文檔的“骨架”雛形。這個圖我會經過若干次調整，直到覺得比較完美了，才開始編寫文檔。
當然了，在修訂思維導圖的過程中，肯定要陸續的收集相關資料，文字、圖片、參考文檔等等。這個時候就用到了OneNote這個軟件，它是Office2010中的套件之一，用於收集資料非常方便。它支持圖文混排，可以隨時摘錄，會自動存檔，帶錄音功能，可以無限制的划分標簽。如果說MindManager在搭建文檔的“骨架”，它就是在組織文檔的“血肉”。
等一切都妥當了，再把相關文檔模板拿來，把整理好的內容往里面填充，這樣，一個格式完整、思路清晰、內容充實的文檔就出爐了。最后就是排版，這是Word專長。
后記
我發現很多同事用的文檔編輯軟件都不一樣，有用Word2010的，有用Word2003的，還有用WPS的，這不能說不行，但它在文檔交流過程中會造成一些不方便。為什么我們軟件開發的工具會很容易統一，但辦公軟件卻難以統一起來呢？究期原因，我想，還是在大家心里，“研發管理”的地位還遠低於“研發”本身。