作為一個長期混跡于CSDN社區(qū)的人，我對很多擁有高訪問量的博主欽佩不已，特別是在參加了CSDN在舉辦“2014 CSDN博文大賽”及“2015 CSDN-Markdown博文大賽”活動之后。我看到活動中的一些參賽作品條理清晰、文筆流暢、語言優(yōu)美，大都出自程序員之手。我不禁想到一個問題：程序員是否應該注重文檔的編寫？

寫文檔的重要性

對于軟件相關行業(yè)，在學?；騿挝淮蠹乙苍S都已經注意到了，除了要編寫的程序、繪制設計圖之外，還有一個重要的工作便是寫文檔。為什么要寫文檔呢？因 為我們要把自己做的東西展示出來，不光展示給同行看，可能還要展示給其他崗位上的工作人員看，甚至展示給用戶看。如果我們只是會寫程序，不會在文檔中恰當 且優(yōu)雅地描述自己的想法，那么就真正的成為“碼農”了。

我注意了一下，周圍的同事會寫高質量文檔的確實很少。李開復老師在《浪潮之巔》的序言中說到：“我認識很多頂尖的工程師，但具備強大敘事能力的優(yōu)秀工程師，我認識的可以說是鳳毛麟角。”確實，我所認識的同事，能夠在文檔中清晰地表達自己想法的也很少。

有關文檔書寫，我印象很深的問題有如下幾個方面：

1.我們每天都會收發(fā)很多郵件，我仔細看了一下，很多郵件里面的內容要么語句不通順、要么有很多錯別字、要么誤用或沒有標點符號。很多時候，從不同的角度理解，一封郵件有很多不同的意思，讓人感覺不知道它究竟要表達一個什么意思，這樣極大地降低了工作的效率。
2.除了代碼之外，項目也會包含了大量的文檔。打開大部分文檔，看到的第一眼，我就有這幾種感覺：排版不工整、格式不正確、語句不通順、錯別字連篇。一看就知道作者沒有認真寫文檔，并且語句的表達和組織能力也不強。
3.在項目小組成員討論的時候，大家?guī)缀醵荚谡f怎樣把程序寫好，而沒有提到在文檔書寫方面應如何努力去改進。大家似乎一致認為開發(fā)人員的職責就是把程序寫好，其它什么的都是其次的。

有關計算機軟件的傳統(tǒng)定義為：軟件是計算機系統(tǒng)中與硬件相依存的另一部分，軟件包括程序、數據及其相關文檔的完整集合。注意，這里面就提到了“相關文檔”，如果文檔沒有寫好，那么軟件也不能算是優(yōu)秀的軟件。事實上，軟件功能健全，而由于文檔原因出現故障的情況還時有發(fā)生。

一般說來，在軟件開發(fā)過程中，不同階段涉及到的主要文檔如下圖所示：

可見，在軟件的不同階段，需要編寫不同的文檔。在計劃階段，需要編寫詳細設計文檔、單元測試方案文檔和集成測試方案文檔等；在開發(fā)階段，也是這幾個 文檔，不過是修訂版，因為我們在實際開發(fā)過程中，會發(fā)現之前設計不合理的地方或者是考慮不周的地方，這就需要對之前的文檔進行修改；在測試階段，要編寫單 元測試報告、集成測試報告和系統(tǒng)測試報告等；在軟件的發(fā)布階段，要編寫安裝手冊、用戶手冊、升級指導書等，這些文檔主要是面向現場支持人員和用戶的，因此 要盡量寫得通俗易懂，千萬不要有模棱兩可的情況存在，否則就只有等待用戶的投訴了。

要想寫好文檔，我們需要首先糾正一個觀念：文檔不重要。要把文檔放在與程序同等重要的位置。

程序員如何寫出高質量文檔？

既然文檔這么的重要，那么對于程序員來說，我們如何才能寫出一份好的文檔呢？根據我個人的經驗，我們不妨從以下方面入手：

第一，將重要的內容分點描述，而不是雜糅在一起。

例如，有一段描述某軟件功能的話是這樣的：

該軟件模塊在系統(tǒng)中占有重要的地位，它從客戶提供的FTP目錄下獲取文件，并下載到本地的目錄中。接著，它掃描本地目錄， 對讀取到的文件的內容進行解析，并生成新的文件放到本地的另一目錄中。然后，它將該目錄中的文件上傳到客戶指定的FTP目錄中。對于本地目錄中的文件，該 模塊有一個過期清理的機制，清理時間及過期期限可配置。

我們可以看到，上面那段話將軟件功能描述放到一個段落中，讀起來讓讀者云里霧里的。我們可以把內容分點描述，如下：

該軟件模塊在系統(tǒng)中占有重要的地位，其實現的主要功能為：
(1)從客戶提供的FTP目錄中下載文件到本地的目錄中。
(2)從本地目錄中獲取文件進行解析，并生成新的文件放到本地的另一目錄中。
(3)將目錄中生成的文件上傳到客戶指定的FTP目錄中。
(4)清理本地目錄中的過期文件(清理時間及過期期限可配置)。

這樣修改之后，文章的邏輯更加的清晰，可讀性更強，讀者也更容易理解作者所要表達的意思。

第二，將流程性比較強的內容畫成流程圖，而不是僅用文字描述。

一篇圖文并茂的文章才是好文章，如果大家看到一篇好幾十頁的文章全是文字，很容易失去閱讀的興趣。對于某些流程性比較強的內容，如果將文字變成流程圖，則給讀者的感覺是不一樣的。

例如，下面一段文字描述了socket的整個消息流程：

第一步，創(chuàng)建socket。
第二步，綁定指定的IP地址和端口。如果綁定失敗，則跳到第一步。
第三步，啟動監(jiān)聽。如果沒有監(jiān)聽到消息，則程序一直處于監(jiān)聽狀態(tài)；如果監(jiān)聽到了消息，則執(zhí)行下一步。
第四步，循環(huán)從監(jiān)聽隊列中獲取消息，并根據消息內容執(zhí)行相關的操作。

將文字內容畫成流程圖，如下所示：

從流程圖中，我們更容易看出程序的邏輯，讓讀者在一段輕松的閱讀旅程中理解作者所要表達的意思。

第三，將帶數字的內容以圖表的形式呈現，而非用文字描述。

對于某些有參照性質的數字，我們可以用圖表的形式來呈現，這樣可以讓讀者看到相鄰幾組數字的變化情況，文章的表達效果更好。

例如，有下面一段描述：

今年3月份，解決的軟件bug數量為8；今年4月份，解決的軟件bug數量為6；今年5月份，解決的軟件bug數量為10。

可以將以上內容替換成下面的圖表：

從圖中，我們更容易看出前后數字的變化情況，對所描述事物有一個整體的把握。

第四，盡量不要直接在文檔中貼代碼，而換之以偽代碼、流程圖等形式。

也許是為了省事，很多程序員喜歡將工程代碼直接粘貼到文檔中，這不僅會占用大量的文檔篇幅，而且會降低文檔的可讀性。試想，一個從沒有接觸過代碼的 人，如何能夠看懂你在文檔中給出的代碼？即使對于有經驗的程序員來說，一眼看到你寫出來的程序，也不見得能夠一下就明白的。如果你寫的代碼確實很好，想給 別人看，那么在正文中可以只給出設計思想、流程圖等，而在附錄中給出完整的代碼。

以上幾點寫文檔的建議是本人在寫文檔過程中的一些心得體會，不見得都正確，大家可以參考?？偟恼f來，文檔的編寫要遵循簡單易懂的原則，要用最直接明了的方式來表達作者本人的意思。

愛因斯坦曾說過：“科學家應該使用最簡單的手段達到他們的結論，并排除一切不能被認識到的事物”。也就是說，簡單就是美。這個“簡單”的原則同樣可以應用到文檔編寫中，應用到所有的軟件開發(fā)項目中。

其它一些建議

1.改變文檔為輔的觀念，在平常的工作中，對于自己編寫的每一份文檔，均認真對待。
2.對于郵件的編寫，要把自己想說的話準確地表達出來，在發(fā)送郵件之前，再看一下內容是否完整、是否還有錯別字、語句是否通順等。
3.在編寫文檔的過程中，要嚴格參照項目組規(guī)定的模板來完成。在寫完文檔之后，對文檔進行語法檢查，以糾正錯別字和有語法錯誤的地方。一般說來，有語法錯誤的語句下面會有一條綠色的波浪線。在提交文檔之前，再通讀一下整個文檔，看是否還有疏漏和不足。
4.在工作之余，可以讀一些能夠提高語言表達能力和寫作能力的書籍或文章，看一下別人是怎樣清晰地闡述自己思想的。例如，經常閱讀CSDN上面優(yōu)秀博主的博文就是一個提高自己寫作能力的好辦法。

總結

總的說來，和做其它事情一樣，書寫文檔也反映了一個人的態(tài)度問題。寫出高質量的文檔，不僅可以提升個人的形象（如果你看到一篇好文檔，是不是也對作者有較高的評價？），還能夠提升產品在客戶心中的形象。如此分析，多花些心思來書寫文檔真的是很有必要。

要想做好一件事情，需要我們從各個方面來努力。在開發(fā)軟件的過程中，寫好代碼很重要，清楚明了地在文檔中表達自己思想同樣非常的重要。“代碼”和“文檔”就像是一個人的左膀右臂，一定要讓兩者均衡發(fā)展，而不能夠只顧其一。