我在《專業嵌入式軟件開發》一書中指出，編寫言簡意駭的文檔是實施高質高效軟件開發的關鍵要素之一。在此結合自己的工作體會，再談一談軟件開發活動中文檔的重要性。切入正題之前，先讓我們瀏覽二個工作場景。
A君剛加入一個代碼規模超過百萬行的複雜通訊項目。在熟悉項目的過程中發現，上手新項目只能依靠幾份單薄的PPT文檔，而無法獲得象樣的系統架構文檔、各子系統的概要設計文檔和子系統間的接口文檔。面對這樣的狀況，A君只能無奈而痛苦地面對艱難的學習曲線。
初涉某新項目的B君被安排將其他團隊最新發布的平臺軟件集成到產品中，B君在集成的過程中倍感焦慮。問之爲何，答曰：“沒有任何文檔告訴我如何集成，我根本無法知道集成有哪些關鍵的檢查步驟，集成工作只能找這個人問、那個人聊”。
相信這兩個工作場景很多讀者並不陌生，或似曾相識。然而，絕大多數經歷這些場景的同仁仍麻木地看着後來人經歷着同樣的痛苦 — 無休止的痛苦。爲什麼不寫文檔解決這類問題？很典型的回答是：1）代碼就是文檔；2）沒有時間寫。
看來，持“代碼就是文檔”觀點的人認爲，讀代碼與讀文檔是一回事，具有同樣的溝通效果。不！爲了解釋爲什麼，我們得先看一看代碼是如何在不寫設計文檔的情況下編寫出來的。
程序員在理解需求的情形下，會先通過分析構思出如何通過代碼實現需求（這裏假設程序員的設計能力很好，所構思的設計有模有樣），之後通過編碼表達出自己的設計（再假設程序員的編碼能力很強）。很顯然，設計構思與最後獲得的代碼在表達層面上處於不同的抽象層次，前者更抽象。基於我們的生活經驗我們不難認同，相對抽象（不要偏激地理解爲非常抽象）的內容更容易在人與人之間取得良好的溝通效果。
再看一看代碼被人掌握的過程。毫無疑問，代碼只能一段一段地看，閱讀者通過不斷地消化，最終達到在頭腦中重現其所表達的設計。很顯然，這種“重構”活動需要閱讀者運用自己的綜合和記憶能力，是一個從具體到抽象的思維過程。在很多情形下（尤其是大型項目），這是一個很艱難的過程，如果代碼是在“意識流”的指導下編寫出來的，其難度就更不用說了。
閱讀代碼如此，那閱讀設計文檔又有何不一樣呢？很簡單，設計文檔正是用於闡述設計思路的，它直接短路了閱讀代碼時從代碼回塑軟件設計的思維過程，因而具有更好的溝通效果。是的，我也間接地表達了一個觀點 — 軟件設計文檔應着力於闡述設計構思。因此，如果你告訴我“代碼就是文檔”，我會理解成“你的文檔在描述代碼，而非設計”，對於這樣的文檔我完全認同“代碼就是文檔”，而且這種垃圾文檔不寫也罷。對了，對於沒有代碼的工作，比如開發環境搭建，你如何主張“代碼就是文檔”？還有，當你負責實現的軟件模塊如果要被多個團隊採用，在沒有設計文檔的情況下如何實現高效的並行開發？
文檔既然重要，那爲什麼被人如此忽視？首先，這與技術管理者不無關係。在1999年我剛涉足軟件行業時，那時所寫的設計文檔被一遍又一遍地要求修改，在無耐之下，我對技術管理者說“你能給我一個寫得好的樣本參考嗎？”之後，我再也沒有因爲文檔的編寫質量而被“再要求”。爲什麼？因爲技術管理者自己並不知道好的文檔應是什麼模樣、有什麼用，也不能以身作責地告知什麼是好文檔，他只是在《軟件工程》這類書中讀到要有這麼些文檔。十多年過去了，請看看你周圍的技術管理者，他們是不是與我當年面臨的差不多？請不要指責技術管理者，如果那樣，十年後在相同的境況下被指責的人就是你！
技術管理者對開發文檔的不重視，使得團隊在編寫文檔方面少了很多動力，進而最終形成沒有開發文檔的“作坊式”軟件開發文化。具有這種文化特點的團隊有一個很鮮明的特點 — 極大地依賴口口相傳傳遞知識與經驗，對出現的異常難以做出快速響應。
忽視文檔的另一大原因，是將敏捷思想中的“可工作的軟件重於面面俱道的文檔”理解爲“軟件開發可以不寫文檔”。相信不少團隊正是將這一敏捷思想當作不寫文檔的“擋箭牌”。
文檔被忽視的第三大原因與我們的能力現狀有關。就我複審文檔的經驗來看，十個工程師中有九個所寫出來的文檔要麼不知所云、要麼複述代碼實現，文中內容缺乏總結和抽象，而且文檔格式“慘不忍睹”。這類文檔所提供的價值非常有限，看了也白看。加之身邊存在大量的這類文檔，因此我們很容易失調地以爲所有文檔都無用（正確的認知應是“垃圾文檔無用”），惡性循環由此產生。誠然，打破惡性循環的方法是提高我們的寫作能力，而非維持現狀！
在開源軟件項目大行其道並逐漸顛覆傳統軟件產業格局的今天，不少開源項目沒有良好文檔但卻運作得很好的事實也左右着我們對文檔重要性的認知。與開源項目不同的是，大多的商業軟件具有產品上市時間的壓力，對開發效率和開發進度控制有着完全不同的要求，因而我們不能簡單地以開源項目作爲類比。另外，工作於開源項目的工程師技術水準相對高，這在某種程度上緩解了開源項目文檔缺乏所帶來的負面影響。對了，很多著名的開源項目都有人爲之出書立著，不是嗎？
那文檔到底有什麼好處呢？先從團隊的角度加以審視。首先，文檔有助於新手更快地上手項目。軟件設計文檔能讓新手更快地掌握遺留系統的軟件實現；開發環境搭建文檔能幫助新手高效地構建開發環境以投入到人力緊張的項目中；開發流程文檔能讓新手遵循已有的開發實踐；等等。
其次，文檔有助於傳承團隊知識和沉澱經驗教訓。相信沒有人願意看到如火如荼的項目因爲某位團隊成員的離開而“熄火”，也不願碰到因爲人員的流動給自己的工作帶來極大的痛苦，知識和經驗教訓的文檔化有助於我們緩解甚至克服這類問題。
再次，文檔有助於代表個體爲團隊所做出的貢獻。健康的團隊不能只是“生產”代碼，還得防範因爲人員流動而產生前面所談到的知識、經驗教訓的流失，這是團隊建設的重要組成部分。個體對團隊的貢獻不在於你多能說或喊，而在於你多能寫（包括代碼和文檔）。（另：@出版人周筠
老師在微薄中提到“農業社會靠喊，商業社會要寫”的觀點，很具概括性）
從個體角度，文檔寫作能力關乎我們的職業發展和職場旅程！
我也是從“代碼論英雄”的時期走過來的，也曾以爲能寫出“好”的代碼就行了（沒有最好，只有更好！）。然而，現在我知道，當寫作能力提高之後，軟件設計和代碼編寫能力也隨之更強，容易做到時刻思考“如何通過設計讓代碼具備更好的溝通性”（編程是一種創造性的溝通！）。寫好文檔需要我們具備良好的洞察力和概念塑造能力，這些能力都是高質高效軟件開發所需要的。總之，寫作能力的提高有助於提升軟件開發能力。現實之所以有那麼多難懂的代碼，正因爲程序員活在代碼世界，而非設計之中。在更具體的代碼世界覺得好的代碼，一旦站在更抽象的設計層面，會發現仍有很大的提升空間。
在我看來，出色的程序員一定具備良好的寫作能力，因爲他們喜歡發表自己的意見和影響他人，而輸出文檔就是一種途徑。還有，如果想成爲一名合格的軟件架構師，寫作能力是必過之關，否則即使擔綱了軟件架構師一職也只能是“坑人害己”，因爲軟件架構師的能力極大地影響着軟件開發的上游質量。
編寫文檔也是我們職業化的需要。在Motorola工作期間剛涉足系統工程師一職時，“菜鳥”的我分不清何時用SECCB（System Engineering Change Control Board）、何時用BCCB（Business Change Control Board），通過查看流程文檔發現，其中定義好了使用兩者的標準是什麼。當時給我的感覺真的是震驚，寫這部分內容的人（或組織自身）一定也經歷了我當時的那種成長痛苦，他通過文檔化爲後人解決了這一苦惱。你敢設想解決這種苦惱的方法經歷幾年、甚至幾十年的口口相傳仍“原汁原味”嗎？我相信職業化可以包含很多內容，但“我爲人人，人人爲我”一定應包含其中，這是可持續發展所必須涵蓋的，編寫文檔就是踐行這一主張的。
編寫文檔也是我們更好地學習和享受生活的需要。“勤勞的中國人”生怕在工作中空下來，喜歡樂此不疲地重複解答別人所問和身體力行地傳授自己所能。難道不能寫成文檔與人分享，然後空出時間來學習和享受生活？（好吧，“IT民工”沒錢沒生活，起得比雞早，睡得比狗晚。自找的！）
隨着職場旅程的變遷，我們不斷地通過編寫更多的代碼收穫經驗，收穫經驗之餘我們只想在履歷上寫上“曾工作於某項目”嗎？一個項目的代碼我們只要三年不去接觸，就差不多忘得一乾二淨了，你以爲三年以後會仔細地閱讀代碼瞭解當時的設計和教訓（那時物是人非了，你不會有這樣的激情的！相信我）？爲什麼不通過文檔，以總結的方式記錄下來呢？如果在我們的職場旅程中不斷地通過文檔記錄下曾做過的項目，日後瀏覽起這些文檔一定會是一種享受（當然，你留下的是垃圾文檔除外）。文檔質量與數量是體現我們職場厚度的更高形式！我現在拿起2000年寫的設計文檔都會很感慨
— 哇，我那時能寫出這樣水準的文章！（切，其實有很多地方需要改進。別自戀！?）
爲了讓本文不致於產生另一個象“可工作的軟件重於面面俱道的文檔”那樣的誤會，我得就文檔的要求做一點小小的補充。我並非主張在沉重的“軟件工程”面前又倡導另一個複雜的“文檔工程”。文檔的目的在於溝通，其中內容應突出要點地“點到爲止”，以總結和抽象作爲寫作指導。同樣的目的，如果能用最少的頁數說清道白就是水平。文檔重質不重量！
該死的“代碼就是文檔”，害得我沒有很好地欣賞昨晚的“中國好聲音”，還搭上了一晚只睡了六個小時的覺。如果你還得說“文檔就是代碼”，請準確地說“文檔是一種代碼”。
對了，都要結束了。還沒有指出爲什麼有人會提出“沒有時間寫文檔”。以我的經歷來看，那人沒有說實話，他其實應說“我沒有那個寫作能力”。
【本段是收到讀者的回覆後加的】如果讀者將“代碼就是文檔”理解爲“寫代碼就得象寫文章一樣讓之通俗易懂”，那很好。但以我的工作經歷來看，很多人對之的理解卻是“有了代碼就不用寫文檔”。無論如何，作者的本意是指出文檔對於高質高效的軟件開發是必不可少的。從編程中的命名角度來看，“代碼就是文檔”絕對不是一個好的“命名”，它仍然“該死”！