從程序員到項目經理（29）：怎樣寫文檔

在軟件項目中，文檔既是一項的重要成果，也是項目管 理的有力工具。經過文檔，能夠穩定、明確的傳達信息，實現項目內的有效溝通。因此寫文檔對項目經理來講，是一項必備的技能。

然而不少項目經理懼怕寫文檔，彷佛這是一個很麻煩、 很困難的工做。其實會不會寫文檔，只是一種外在的表現，經過一我的寫文檔的狀況，能夠看出他對工做的理解程度，發現潛在的問題和風險。一個合格的項目經理，不但不會怕寫文檔， 並且會以爲這是一件簡單、很天然的情，就像一我的吃飯、喝水同樣，何難之有？

（本人拙做《程序員第二步 -從程序員到項目經理》即將面市，敬請關注~~ 噹噹網已可預訂http://product.dangdang.com/23365823.html） 

1.編寫文檔的常見問題

每一個項目都要寫很多文檔，好比項目實施計劃、系統需 求說明書、系統概要設計設計、系統詳細設計、測試計劃……在很多軟件項目中，大部分文檔寫出來只是爲了應付檢查或驗收，若是要對這些文檔較真的話，就會發現它們存在着各類各樣的問題。

該 有的文檔沒有

什麼叫該有的文檔？我想有兩點含義：一是合同、招標 文件規定必須提交的文檔；二是項目自己確實須要的文檔。若是僅僅是前者沒有，我通常不會怪項目經理，由於過後能夠補上。但若是是第二種狀況，那就不僅是文檔自己的問題了。試想 ，若是項目執行了一半，尚未項目計劃，顯然就沒法就事論事只談論計劃了，這反映了項目經理對整個項目的管理具備隨意性，盲目性；若是沒有設計文檔就完成了大部分編碼工做，那 麼代碼的質量就得打上一個大大的問號了。

項目須要的文檔沒有，要麼是項目經理的疏忽，要麼是 寫不出來，這自己也是很危險的信號。若是項目經理連必需的文檔均可以疏忽，說明他的工做徹底沒有系統性，那他對項目的管理工做怎麼值得信任呢？若是是寫不出來，這說明項目經理 沒有想好怎麼作，一樣也是一件很危險的事情。

丟 三落四，內容不完整

打開文檔一看，老是有一些你想看的內容找不到，或者 對關鍵的內容輕描淡寫，這多少會讓人以爲有點生氣。項目計劃沒有工做分解，設計文檔沒有系統邏輯結構，項目週報沒有當前進度狀況，試運行報告沒有系統運行的統計數據 ……出現這樣的狀態，說 明項目經理缺少經驗，對項目沒有整體的認識，更加把握不了工做的重點。

照 搬模板，徒具形式，內容空洞

這種文檔還真讓人有點迫不得已。乍一看，文檔格式規 範、內容完整，彷佛沒什麼問題，但內心總以爲少了一些東西，看完了什麼也沒記住，彷彿沒看過同樣。簡單的說，就是沒有實質性內容，缺少對問題的具體分析，一樣的內容，改一下名 字，能夠給其它項目用。

這樣說項目經理可能會不服氣：我文檔有幾百頁，怎麼 會沒內容呢？好吧，咱們來清理一下，把模板自帶的內容去掉、把合同和招標文件中Copy的內容去掉、把網上抄的內容去掉、把不相關的內容去掉、再把不重要內容去掉，再來看看究竟還剩下幾頁？這剩下的內容纔是真 正有價值的東西。若是這一部份內容不多，你文檔越長，就會越像懶婆娘的裹腳布，讓人生厭。

看這樣的文檔，讓人以爲就像吃了蒼蠅同樣難受。有人 將這種文檔稱之爲「模板殭屍」，真是既準確、又解恨。這種文檔徒具形式，沒有靈魂、沒有精神，就像一具只有骨架、沒有血肉的殭屍。

寫出或者接受這種文檔的項目經理也很可怕。 他有經驗，可是沒想法；他知道流程，但不知道變化；他能把握形式，但把握不了內在；他明白要作什麼，卻永遠也理不清楚工做的內容；他寫的內 容不少，腦中卻幾乎一片空白。他們寫出來的文檔像殭屍，作項目也像被殭屍附身同樣，只能沿着固定的路徑一蹦一跳的前進，哪怕前面有深淵，他也會直接跳下去，因 爲他壓根就看不到！

2.怎樣寫好文檔

我見過很多工做十年以上、管過項目五年以上的同事， 對於寫項目文檔仍然是愁眉苦臉、痛苦不堪。難道寫文檔真的有這麼難嗎？怎樣才能寫出合格的項目文檔呢？

最核心的一點，寫你所想的

俗話說：「言爲心聲」，寫做也是一種 「言」，一樣體現了做者的心裏想法。寫項目文檔，最重要的就是要寫本身的真實想法，展現本身的思路。若是說寫文檔有什麼訣竅的話，這就是最重要的訣竅。從哲學上來講 ，這是知行合一的重要一環；從寫文檔自己來講，只有這樣才寫得好、寫得快。因此若是有誰說本身不會寫文檔，咱們首先應該想到的不是什麼技巧問題，而是他真的想好了嗎？

體現了知行合一

「知行合一」也就是「想」和 「作」應當保持一致。知行合一最簡單的方法，就是想了就去作，由想直接到作。在軟件行業我的英雄主義年代，程序員有好的想法，而後實現它，就有可能成就一段傳奇，例 如UCDOS、WPS、RichWin、江民殺毒等都是那個時代的產物。由想直接到作，這對於一我的完成的 簡單工做是能夠的，但並不適合於由多人協做完成的複雜任務，由於團隊做戰還有一個關鍵環節——溝通。

溝通有口頭和書面兩種方式，也就是說和寫。想、說、 寫、作四者統一，才完總體現了項目中的知行合一。說你所想的，寫你所想的，不然就是言不禁衷、表裏不一；而後作你所說的，作你所寫的，這叫說到作到、一言既出;駟馬難追。

圖 想說寫作的統一

因而可知，寫你所想的，是知行合一的重要體現。

寫所想的才能寫得好、 寫得快

爲何有些人寫文檔寫得很慢 、以爲很痛苦呢？最根本的緣由就是由於他沒有想法，或者說沒想好，肚子裏沒貨天然拿不出來。比 如說，若是你不熟悉Java技術，讓你 來寫一個Java系統的設計文檔，你自 然不知從哪裏下手，縱使你有莫言同樣的文采和想象力，也沒有辦法完成。

寫你所想的，其實只是把想法 謄到紙上而已，就像把杯子裏的水倒出來同樣。有思路的話，固然能寫得快、寫得好。若是沒有想法 ，千萬不要不懂裝懂，到網上處處複製一些看上去相關的內容來填補，由於這會誤導別人，雖然掩蓋了本身的無知，但也掩蓋項目隱藏的問題和風險。因此對於沒有想清楚的地方，最好的 處理方法就是直接寫上「沒想好」三個大字，等想好了再補上。記住：說假話的人最辛苦，由於他老是要琢磨該怎樣編故事，怎樣自圓其說。講真話的人最輕鬆，寫文檔就是要 寫本身的真心話。

不要拘泥於形式

有些人說：「我有想法，就是寫不出來。」 這種狀況多半是因爲寫做者拘泥於文檔的形式，不知該如何下筆。這樣的話，有一個簡單的方法：先把你的想法說出來，用手機把聲音給錄下來，而後對照錄音來整理文檔。也就是說，我 們要像說話同樣寫文檔，說話是很天然的事情，寫文檔也是很天然的事情。若是你沒辦法說清楚，那估計神仙也法辦法了——除非有誰懂得讀心術。

文檔最重要的是內容和思想，讓讀者能讀懂你的思路， 而不是構思有多精巧，語言有多優美。若是老是在琢磨先寫什麼，再寫什麼，用什麼詞，怎麼能快得了呢？

不拘泥於形式的另外一含義是不要有過多形式化的內容。 有時一篇30頁的文檔，項目背景、建 設目標、參考資料之類就佔掉15頁， 而且在每一篇中都千篇一概。這些東西不是徹底沒用，但過多就會影響對文檔重點的把握，儘可砍掉或簡化。

另外不要湊篇幅。項目文檔是用來指導項目實施的，因 此把問題寫清楚就能夠了，多寫無益。有些人寫文檔時，喜歡問要寫多少頁，其實這根本不該該成爲一個問題，若是把想說的都說清楚了，你管它有多少頁呢 ？

文 檔結構要具邏輯性

在第三章中，曾經提到PMBok項目管理理論遵循結構化的思想，即自頂向下、逐層分解。 這一規律一樣能夠用來指導文檔的編寫，項目文檔在結構上一樣應該是「結構化」的，自頂向下、逐層分解，造成金字塔形的結構。

還記得在學校里老師教咱們怎樣寫做文了嗎？要按 「總分」或「總分總」的結構來寫，這其實也是結構化方法的體現。結構化方法之因此放之四海而皆準，是由於它符合人對事物的認識規律。

設想咱們要研讀一本書，通常咱們首先會看書名、做者 ，再看目錄、前言或簡介，對全書全造成一個整體的印象，這是「總」的過程。而後咱們會逐章逐節的閱讀，一步一步消化全書的內容，這是一個「分」的過程。部 分讀者在讀完之後，可能還會對全書的內容進行再次總結回顧，以進一步加深理解，這又是一個「總」的過程。經過這樣一個「總分總」的過程，咱們造成了對事物 的深入理解。

因此一本書按照金字塔結構來組織文檔，其實就是爲了 迎合讀者，下降他們理解的難度，讓他們只須要更少的時間就能夠對整個文檔的精要有一個完整準確的理解。做者寫得輕鬆、讀者讀得開心，真是皆大歡喜。

結構化方法不但適用於文檔的總體結構，一樣適用於局 部結構，例如文檔的某一節。只要事物具備必定的複雜度，咱們均可以用這種方式將其講得更加透徹。

採用結構化方法來編寫文檔還有一個好處，就是能夠檢 驗思惟的嚴謹性。結構化方法的一個重要工做就是對事物進行分解，而分解的過程實際上是一個再次深刻思考的過程，例如分解的標準是什麼，上層結構是否完整的包含了下層結構等，從而 發現被遺漏的問題，並進行完善。

注 意排版

文檔排版是許多人容易忽視的問題。一分內容上乘的文 檔，若是用工整悅目的排版來展示，那就是錦上添花了，反之就有損文檔做者的形象。這就比如一我的心靈美當然重要，但若是穿着邋遢，面目可憎，也不大可能會受到別人的歡迎。

排版並不是難事，只須要投入很小工做量，就能夠爲文檔 得到必定的加分，這就是排版的價值。事實上，排版仍是對讀者尊重的表現。做者多花一點點精力，就可讓讀者擁有更好的閱讀心情，更快的閱讀速度，實在是一種設身處地爲他人着想 的美德。