關(guān)于文檔編寫

寫文檔的困惑

寫文檔不像寫代碼，它沒(méi)有明確的好與壞，更沒(méi)有明顯的正確與不正確。也正因?yàn)榇耍瑢?duì)于寫慣了代碼的程序員來(lái)說(shuō)，寫文檔是無(wú)比痛苦的，完全找不著北。

寫短了，人家說(shuō)沒(méi)寫清楚，太不詳細(xì)；寫得長(zhǎng)了，人家說(shuō)太瑣碎，那么長(zhǎng)，哪有精力看。

領(lǐng)導(dǎo)說(shuō)，“這個(gè)問(wèn)題簡(jiǎn)單，兩三頁(yè)隨便描述一下就行了?！蹦闳粽媸侵粚憘€(gè)兩三頁(yè)，百分之百挨批。

又要言簡(jiǎn)意賅，又要表述詳盡。這比寫代碼要費(fèi)勁多了。

我們寫代碼時(shí)，講什么重構(gòu)呀重構(gòu)，有幾個(gè)人寫完代碼重構(gòu)的？沒(méi)幾個(gè)吧。有哪一個(gè)寫完程序重構(gòu)個(gè)十來(lái)回的？亙古少有吧。而寫文檔，隨便一個(gè)文檔，被重構(gòu)個(gè)十來(lái)回、幾十回，甚至推倒重來(lái)個(gè)幾回都很正常。

寫代碼與寫文檔，完全是兩個(gè)境界。要不怎么說(shuō)，寫代碼的工資，不如寫文檔的；寫文檔的工資不如寫PPT的。PPT相對(duì)于文檔更加精煉，所以寫起來(lái)更困難。

看文檔的困惑

商務(wù)經(jīng)理寫的立項(xiàng)說(shuō)明，研發(fā)經(jīng)理看不明白；項(xiàng)目經(jīng)理寫的需求分析，開發(fā)人員看不明白，包括我自己寫的文檔也有別人看不懂的時(shí)候，呵呵。

當(dāng)然了，我這么說(shuō)，會(huì)有人很不服氣，“哪里不明白？你說(shuō)哪里不明白？哪不明白你問(wèn)我，我給你講?！?/span>

尤其常見的是，當(dāng)新員工拿到開發(fā)資料后，看不懂，只好問(wèn)老員工，老員工不耐煩，“文檔上不是寫的很清楚嗎？找不著？這里，這里，不是嗎？……看不懂？你自己看不懂怨誰(shuí)？”新員工不吭聲了，郁悶到一定程度就悄悄辭職了，剩下牛逼哄哄的老員工發(fā)牢騷。

我也坦誠(chéng)，大多數(shù)項(xiàng)目文檔，我都沒(méi)有從開頭看到結(jié)尾過(guò)，哪怕兩三頁(yè)的文檔，都是跳讀。其實(shí)不僅是項(xiàng)目文檔，除了小 說(shuō)，幾乎所有的書籍、資料我都是跳讀，瀏覽一下大概意思就完事兒了，具體到某個(gè)問(wèn)題時(shí)，再著重閱讀相關(guān)章節(jié)。問(wèn)題在于，重點(diǎn)問(wèn)題往往沒(méi)有重點(diǎn)表達(dá)。

一般閱讀文檔都會(huì)通過(guò)文檔結(jié)構(gòu)圖來(lái)查閱，那個(gè)文檔結(jié)構(gòu)圖其實(shí)就是文檔的骨架。一個(gè)完整的文檔自然是從頭到腳都有的，但我們并不會(huì)從頭看到腳。就像我們看一個(gè)人一樣，如果對(duì)方胳膊腿少一樣我們都會(huì)感到吃驚，但我們面對(duì)對(duì)方時(shí)，卻不會(huì)從頭到看到腳，如果真這樣，實(shí)在太不禮貌了。我們只需關(guān)注重點(diǎn)。

文檔模板的編寫

單純依靠作者的文字能力、創(chuàng)作能力寫出好的文檔是不靠譜的，畢竟大家不是專業(yè)寫手?；舅悸愤€是“套模板”，軟件工程有國(guó)標(biāo)的文檔模板，也有ISO的文檔模板，也有CMMI的文檔模板，可是任何一個(gè)模板拿過(guò)來(lái)，都不好往上套，實(shí)在讓人郁悶。究其原因，那些模板只是一個(gè)殼，沒(méi)有任何編寫指導(dǎo)，編不出來(lái)東西。

我想，好的文檔模板應(yīng)該遵循如下原則：

可選、可刪、可填、可編；

能夠讓作者打勾選擇的內(nèi)容項(xiàng)，盡量打勾選擇，例如文檔保密級(jí)別，可以提供三項(xiàng)供選擇“□普通 □保密 □機(jī)密”而不是讓作者去填寫，他有可能不知道該填什么；

其次是“可刪”，即內(nèi)容可以刪減，模板中盡可能提供一些常用的文檔段落，例如，文檔的目標(biāo)讀者，可以在模板中列舉出盡可能多的目標(biāo)讀者，如“目標(biāo)讀者包括：總經(jīng)理，技術(shù)總監(jiān)，項(xiàng)目經(jīng)理，客戶經(jīng)理，需求分析人員，系統(tǒng)架構(gòu)師，項(xiàng)目建設(shè)方負(fù)責(zé)人”；作者在編寫文檔時(shí)根據(jù)需要?jiǎng)h除多余的，如果讓作者增加內(nèi)容，他可能不太容易想的周全。

再其次是“可填”，前文說(shuō)過(guò)，文檔往往重點(diǎn)內(nèi)容沒(méi)有重點(diǎn)表達(dá)，甚至?xí)z漏關(guān)鍵問(wèn)題的描述，原因也不是作者不想去寫清楚，往往是事情多，一時(shí)思慮不周造成的。那么在模板中盡可能把需要描述的內(nèi)容列舉出來(lái)，例如，項(xiàng)目概述部分，涉及項(xiàng)目目標(biāo)、功能范圍、工期約束、承建單位、項(xiàng)目規(guī)模、驗(yàn)收方式等等，在模板中逐個(gè)列舉，供作者填寫，這樣就不會(huì)遺漏內(nèi)容項(xiàng)。

最后，就是“可編”了，畢竟文檔中還有很多內(nèi)容需要作者根據(jù)具體的項(xiàng)目情況需要編寫，這個(gè)工作有一定的創(chuàng)造性，也最讓人感覺(jué)困難，建議編寫時(shí)參考以往的文檔，比葫蘆畫瓢是最基礎(chǔ)技法。

大家可能會(huì)想，有這樣的模板真是太好了，可這樣的文檔模板容易做出來(lái)嗎？的確不太容易，僅靠項(xiàng)目經(jīng)理來(lái)組織編寫文檔模板是完全不夠的，如果公司有項(xiàng)目管理部門，或項(xiàng)目管理委員會(huì)（PMO）出面來(lái)處理這個(gè)事情，會(huì)好一些。

文檔內(nèi)容的編寫

文檔編寫比較麻煩，我在這里說(shuō)一下我的編寫心得。

在文檔的編寫過(guò)程中，我用的最多的軟件并不是Word，而MindManager與OneNote，Word僅用于最后的文檔編排與修訂。

MindManager顧名思義是思維管理的工具，可以用它畫思維導(dǎo)圖、結(jié)構(gòu)圖等，還可以進(jìn)行頭腦風(fēng)暴。當(dāng)我要開始編寫某個(gè)東西時(shí)，我一般會(huì)用MindManager的頭腦風(fēng)暴功能，把自己能想到的、相關(guān)的所有內(nèi)容，都敲出來(lái)，然后把這些內(nèi)容進(jìn)行歸納、增刪、編排，很快一個(gè)像八爪魚一樣的思維導(dǎo)圖就出來(lái)了，這其實(shí)就是文檔的“骨架”雛形。這個(gè)圖我會(huì)經(jīng)過(guò)若干次調(diào)整，直到覺(jué)得比較完美了，才開始編寫文檔。

當(dāng)然了，在修訂思維導(dǎo)圖的過(guò)程中，肯定要陸續(xù)的收集相關(guān)資料，文字、圖片、參考文檔等等。這個(gè)時(shí)候就用到了OneNote這個(gè)軟件，它是Office2010中的套件之一，用于收集資料非常方便。它支持圖文混排，可以隨時(shí)摘錄，會(huì)自動(dòng)存檔，帶錄音功能，可以無(wú)限制的劃分標(biāo)簽。如果說(shuō)MindManager在搭建文檔的“骨架”，它就是在組織文檔的“血肉”。

等一切都妥當(dāng)了，再把相關(guān)文檔模板拿來(lái)，把整理好的內(nèi)容往里面填充，這樣，一個(gè)格式完整、思路清晰、內(nèi)容充實(shí)的文檔就出爐了。最后就是排版，這是Word專長(zhǎng)。

后記

我發(fā)現(xiàn)很多同事用的文檔編輯軟件都不一樣，有用Word2010的，有用Word2003的，還有用WPS的，這不能說(shuō)不行，但它在文檔交流過(guò)程中會(huì)造成一些不方便。為什么我們軟件開發(fā)的工具會(huì)很容易統(tǒng)一，但辦公軟件卻難以統(tǒng)一起來(lái)呢？究期原因，我想，還是在大家心里，“研發(fā)管理”的地位還遠(yuǎn)低于“研發(fā)”本身。