本文大部分內容翻譯總結自《Software Engineering at Google》 第10章節 Documentation。 另外，該書電子版近日已經可以免費下載了 https://abseil.io/resources/swe_at_google.2.pdf，有興趣的同學可以下載翻閱下。 首先宣告，本問所說的文件不僅限於純文字文件，還包含程式碼註釋(註釋也是一種特殊形式的文件)。
很多技術人自己非常輕視技術文件的書寫，然而又時常抱怨文件不完善、質量差、更新不及時…… 這種在程式猿間普遍存在的矛盾甚至已經演變成了一個段子。
文件的重要性
高質量的文件對於一個組織或團隊來說有非常多的益處，比如讓程式碼和API更容易理解、錯誤更少；讓團隊成員更專注於目標；也可以讓一些手工操作更容易；另外如果有新成員加入的話有文件也會讓他們更快融入……
寫文件有比較嚴重的收益滯後性，不像測試，你跑一個測試case，它能立即告訴你是對還是錯，它的價值馬上就體現出來了。而寫一份文件，隨著時間的推移，它的價值才會逐漸體現出來。 你可能只寫一次文件，將來它會被閱讀上百次、上千次，因為一份好的文件可以在未來替你向別人回答類似下面這些問題。
- 為什麼當時是這麼決策的？
- 為什麼程式碼是這樣實現的？
- 這個專案裡都有哪些概念？
- ……
寫文件同樣對於寫作者也有非常大的收益：
- 幫你構思規範化API： 寫文件的過程也是你審視你API的過程，寫文件時會讓你思考你API設計是否合理，考慮是否周全。如果你沒法用語言將API描述出來，那麼說明你當前的API設計是不合理的。
- 文件也是程式碼的另一種展現： 比如你兩年後回過頭來看你寫過的程式碼，如果有註釋和文件，你可以很快速理解程式碼。
- 讓你的程式碼看起來更專業： 我們都有個感覺，只要文件齊全的API都是設計良好的API，雖然這個感覺並不完全正確，但這兩者確實是強相關的，所以在很多人眼裡，文件的完善度也成為衡量一個產品專業度的指標。
- 避免被重複的問題打擾： 有些問題你只需要寫在文件裡，這樣有人來問你的時候你就可以讓他直接去看文件了，而不是又給他解釋一遍。
為什麼大多數人都不喜歡寫文件？
關於文件的重要性，每個技術人或多或少都知道一些，但很多人還是沒有寫文件的習慣，為什麼？ 除了上文中提到的文件的收益滯後性外，還有以下幾點原因：
- 很多工程師習慣將寫程式碼和寫作割裂開，不僅僅是在工作上，而且在思想上就認為它們是完全不相關的兩項工作，這就導致好多人重程式碼不重文件。
- 也有很多工程師認為自己不善寫作，索性就不寫了。 這實際是個偷懶的藉口，寫文件不需要華麗的辭藻、生動的語言，你只需要將問題講清楚即可。
- 有時候工具不好用也會影響的文件寫作。如果沒有一個很好的寫作工具將寫文件嵌入到開發工作流程中的話，寫作確實會增加工作的負擔。
- 大多數人將寫文件看做是工作的額外負擔。 我程式碼都沒時間寫，哪有時間寫文件！，這其實是錯誤的觀念，文件雖然前期有投入，但能讓你程式碼的後期維護成本大幅降低，磨刀不誤砍柴工這個道理相信大家都還是能理解的。
如何產出高質量文件
既然理解了好文件的重要性，我們如何保證在時間的長河中維護好一份文件，這裡有些相關的方法論，大家可以參考下。
像管理程式碼一樣管理文件
對於如何寫出好程式碼，整個技術圈已經有好多經驗的總結了，比如書籍《重構》《程式碼簡潔之道》…… 針對各種程式語言，也有相關的規範，比如國外的Google C++規範，國內的阿里Java開發規範等…… 但對於文件 似乎相關的資料卻很少。但實際上，不應該把文件和程式碼割裂開來，你可以簡單粗暴地認為文件其實就是用一種特殊語言書寫的程式碼，這種語言就是人類的語言。這麼想的話，實際上我們很多在程式碼和工程中總結出來的經驗，也可以直接用在文件中，比如：
- 有統一的規範
- 有版本控制
- 有明確的責任人維護
- 有變更Review機制
- 有問題的反饋和更新機制
- 定期更新
- 有衡量的指標(比如準確性，時效性)
明確你的讀者是誰
寫文件有一個很常見的錯誤，那就是很多人文件都是寫給自己看的，這種情況下就會導致你的文件只有自己或者和你有相似知識背景的人才能看懂，團隊較小時這種問題還好，你們都做著類似的工作，所以也都能看懂文件。但當團隊逐漸壯大後，問題就會凸顯出來，新人有時候有著和你不同的工作背景，甚至現在都做著不同的工作內容，這時候你之前寫的文件他們就很難讀懂了。
所以在寫文件之前請明確你文件可能的讀者會是哪些人，然後針對他們的特點著重關注如何才能讓他們理解。當然，文件也不一定要非常嚴肅和完美，只要能向你潛在的讀者說明問題即可。 記住文件是寫給別人看的，不是給自己看的。
根據專業水平可以大致將讀者分為三種 新手、老手和專家，針對不同水平的人寫作需要有側重點。比如針對新手，你需要重點介紹下里面涉及到的術語和概念，然後詳細講解具體的的實現。相反，針對專家 你可以省去這些額外的資訊。注意，這裡沒有嚴格的標準，因為有些文章新手會看，專家也會看， 這裡還是需要具體情況具體分析。
另外一種對讀者分類的方式就是根據讀者閱讀文件的目的來分類，比如有人知道自己遇到了什麼問題，就是來找解決方案的。還有一批人只有一個簡單的想法，但不知道具體的問題。舉個例子，以讀資料庫慢為例，前者已經知道資料庫慢可能是因為資料量巨大且沒有加索引，解決方案很簡單 加索引，這時候他可能需要知道的是如何正確地加索引。而後者可能著重關注的是為什麼讀資料庫會慢，這時候你可能需要額外重點介紹下資料庫相關的原理。
清晰的分類
文件大致可以分為以下幾種型別，每種型別也有自己不同的特點和寫作側重點。
參考文件
參考文件也是大部分開發人員日常會使用和書寫的文件，比如我們使用某個框架或者工具，都會有API說明文件，這就屬於參考類文件。 它並沒有太多的要求，只要能向讀者展示清楚如何使用即可，但無需向讀者講明具體的實現。
注：參考文件並不僅限於API文件，還包括檔案註釋、類註釋、方法註釋，要求都是能準確說明其用法。
設計文件
很多公司或者團隊在專案開始前都要求有設計文件，設計是專案實施的第一步，所以在設計文件書寫的過程中要求儘可能考慮周全，例如該專案的儲存、互動、隱私……
好的設計文件應該包含以下幾個部分：
- 設計目標
- 實現的策略
- 各種利弊權衡和具體決策
- 替代方案
- 各種方案的優缺點
寫設計文件的過程也你對整個專案做規劃、思考可能出現問題的過程，設計的越詳細、思考的越多，未來遇到問題的可能性就會越小。
引導類文件
引導類文件也很常見，一般都是Step by Step的形式。比如我們在使用某個框架或者工具的時候，一般都會有個引導類的文件一步一步幫助你快速上手。 大家寫引導類文章大家非常容易犯的一個錯誤就是預設了很多背景知識。 一般使用文件都是有開發者寫的，他們都非常瞭解這個工具的相關的知識，所以習慣性的會認為，啊 這個知識點很簡單 使用者也肯定會吧，實際上使用者不一定會。這本質上就是一種認知偏差，這種現象在跨團隊協作 尤其是多端協作的時候也非常明顯。
這型別的文件寫作中，要求寫作者儘可能站在使用者的視角上思考，極力避免出現和使用者的認知偏差，力爭每個步驟做到明確無歧義，每兩個步驟之間做到緊密銜接。
概念性文件
當參考文件無法解釋清楚某些東西的時候，就需要概念性文件了，比如某個API的具體實現原理。其主要是為了擴充參考文件，而不是替代參考文件。有時候這和參考文件會有些內容重複，但主要還是為了更深層次的說明某些問題、解釋清楚某個概念。
概念性文件也是所有文件中寫作最難的，也是被閱讀最少的，所以很多情況下工程師最容易忽視。而且還有另外一個問題，沒合適的地方放，參考文件可以寫程式碼裡，落地頁可以寫專案主頁裡，概念性文件似乎也只能在專案文件裡找個不起眼的角落存放了。
這類文件的受眾會比較廣，專家和新手都會去看。另外，它需要強調概念清晰明瞭，因此可能會犧牲完整性(可以由參考文件補齊)，也有可能會犧牲準確性，這不是說一定要犧牲準確性，只是應當分清主次，不重要的就沒必要說了。
Landing pages(落地頁)
Landing pages就先簡單翻譯成落地頁了，沒想到啥恰當的翻譯詞。比如一個團隊或者專案的導航頁，雖然沒啥具體的內容，但應該包含其他頁面的連結。 比如你新入職一個團隊，比較成熟的團隊都會扔給你一個文件，這個文件裡包含常用的工具、文件連結，這就是這個團隊的落地頁。
落地頁的問題就是隨著時間的推移，頁面可能會變的越來越亂，而且有些內容會失效，不過這些問題都好解決，做好定期的維護和整理就行。
落地頁的技術難度不高，但要求內容的有效性、完整性和分類清晰。
文件Review
在一個組織內，光靠個人去維護文件是不行的，必須得藉助群體的智慧。在一個組織內部，文件的變更也應該像程式碼的變更一樣，需要被其他人Review，以提前發現其中的問題並提升文件的質量。
如何Review文件：
- 專業的視角來保證準確性： 一般由團隊裡比較資深的人負責，他們關注的核心點是文件寫的對不對，專不專業。如果Code Review做的好的話，文件的Review也屬於Code Review的一部分。
- 讀者視角保證簡潔性： 一般由不熟悉這個領域的人來Review，比如團隊的新人，或者文件的使用者。這部分主要是關注文件是否容易被看懂。
- 寫作者視角保證一致性： 由寫作經驗豐富或者相關領域比較資深的人承擔，主要是為了保證文件前後是否一致，比如對同一個專業術語的使用和理解是否有歧義。
寫文件的哲學
上面部分站在組織和團隊的視角來看如何提高文件質量，我們接下來看看站在個人寫作者的視角上如何寫出高質量的文件。
5W法則
5W法則相信大家已經聽的多了，分別是Who What When Where Why，這是一個廣泛被用在各行各業的法則，寫文件當然也能用（5W法則堪稱萬金油，啥地方都能用）。
- WHO： 前面已經說過了，文件是寫給誰看的，讀者是誰。
- WHAT： 明確這篇文件的用途，有時候，僅僅說明文件的用途和目的就能幫你搭建起整個文件的框架。
- WHEN： 明確文件的建立、Review和更新日期。因為文件也有時效性，明確相關日期可以避免閱讀者踩坑。
- WHERE： 文件應該放在哪！ 建議一個組織或者團隊有統一的永久文件存放地址，並且有版本控制。最好是方便查詢、使用和分享。
- WHY： 為什麼要寫這篇文件， 你期望讀者讀完後從文件中獲得什麼！
三段式寫作
寫文章一般都會有三個部分，專業寫作者也講究鳳頭、豬肚、豹尾，這三個詞概括出了好文章三部分應有的特點。技術文件也算是文章的一種，所以一般也都會有這三部分，每個部分有其自己的作用，比如第一部分闡述問題，中間部分介紹具體的解決方案，第三部分總結要點。 但這也並不以為著文件應該有三個部分，如果文件內容比較多，可以將其做更細緻的拆解，可以適當增加一些冗餘的資訊幫助讀者理解文件內容。雖然很多工程師都討厭冗餘 極力追求簡潔，但寫文件和寫程式碼不同，適當的冗餘反而可以幫助讀者理解，很簡單，舉個例子，比如寫作中經常舉例子，舉的例子本質上就是冗餘資訊，生動的例子肯定是能幫助讀者理解抽象內容的（我想這就是自舉
吧）。
結語
目前看到比較好的一個現象就是大家越來越重視文件了，但和測試相比 重視的程度還不夠。測試已經是工作流程中不可或缺的一部分了，而文件依舊還不是。當然這可能和文件本身的特性相關，測試很容易被自動化，也有非常多的客觀指標來評估。文件卻做不到，首先文件的書寫需要人手動介入，而文件的質量也沒有太多客觀的指標評估，提升文件的數量和質量只能從文化和工作流程上去逐漸改變。
最後總結下本文幾個關鍵點：
- 隨著時間的推移和組織規模的壯大，文件會越來越重要。
- 文件也應該是開發流程的一部分。
- 一篇文件只專注在一件事上。
- 文件是寫給讀者看的，而不是給你自己看的。