如何寫好技術檔案——來自Google十多年的檔案經驗

本文大部分內容翻譯總結自《Software Engineering at Google》 第10章節 Documentation， 另外，該書電子版近日已經可以免費下載了 https://abseil.io/resources/swe_at_google.2.pdf，有興趣的同學可以下載翻閱下， 首先宣告，本問所說的檔案不僅限于純文本檔案，還包含代碼注釋(注釋也是一種特殊形式的檔案)，

很多技術人自己非常輕視技術檔案的書寫，然而又時常抱怨檔案不完善、質量差、更新不及時…… 這種在程式猿間普遍存在的矛盾甚至已經演變成了一個段子，

檔案的重要性

高質量的檔案對于一個組織或團隊來說有非常多的益處，比如讓代碼和API更容易理解、錯誤更少；讓團隊成員更專注于目標；也可以讓一些手工操作更容易；另外如果有新成員加入的話有檔案也會讓他們更快融入……

寫檔案有比較嚴重的收益滯后性，不像測驗，你跑一個測驗case，它能立即告訴你是對還是錯，它的價值馬上就體現出來了，而寫一份檔案，隨著時間的推移，它的價值才會逐漸體現出來， 你可能只寫一次檔案，將來它會被閱讀上百次、上千次，因為一份好的檔案可以在未來替你向別人回答類似下面這些問題，

1. 為什么當時是這么決策的？
2. 為什么代碼是這樣實作的？
3. 這個專案里都有哪些概念？
4. ……

寫檔案同樣對于寫作者也有非常大的收益：

• 幫你構思規范化API： 寫檔案的程序也是你審視你API的程序，寫檔案時會讓你思考你API設計是否合理，考慮是否周全，如果你沒法用語言將API描述出來，那么說明你當前的API設計是不合理的，
• 檔案也是代碼的另一種展現： 比如你兩年后回過頭來看你寫過的代碼，如果有注釋和檔案，你可以很快速理解代碼，
• 讓你的代碼看起來更專業： 我們都有個感覺，只要檔案齊全的API都是設計良好的API，雖然這個感覺并不完全正確，但這兩者確實是強相關的，所以在很多人眼里，檔案的完善度也成為衡量一個產品專業度的指標，
• 避免被重復的問題打擾： 有些問題你只需要寫在檔案里，這樣有人來問你的時候你就可以讓他直接去看檔案了，而不是又給他解釋一遍，

為什么大多數人都不喜歡寫檔案？

關于檔案的重要性，每個技術人或多或少都知道一些，但很多人還是沒有寫檔案的習慣，為什么？ 除了上文中提到的檔案的收益滯后性外，還有以下幾點原因：

• 很多工程師習慣將寫代碼和寫作割裂開，不僅僅是在作業上，而且在思想上就認為它們是完全不相關的兩項作業，這就導致好多人重代碼不重檔案，
• 也有很多工程師認為自己不善寫作，索性就不寫了， 這實際是個偷懶的借口，寫檔案不需要華麗的辭藻、生動的語言，你只需要將問題講清楚即可，
• 有時候工具不好用也會影響的檔案寫作，如果沒有一個很好的寫作工具將寫檔案嵌入到開發作業流程中的話，寫作確實會增加作業的負擔，
• 大多數人將寫檔案看做是作業的額外負擔， 我代碼都沒時間寫，哪有時間寫檔案！，這其實是錯誤的觀念，檔案雖然前期有投入，但能讓你代碼的后期維護成本大幅降低，磨刀不誤砍柴工這個道理相信大家都還是能理解的，

如何產出高質量檔案

既然理解了好檔案的重要性，我們如何保證在時間的長河中維護好一份檔案，這里有些相關的方法論，大家可以參考下，

像管理代碼一樣管理檔案

對于如何寫出好代碼，整個技術圈已經有好多經驗的總結了，比如書籍《重構》《代碼簡潔之道》…… 針對各種編程語言，也有相關的規范，比如國外的Google C++規范，國內的阿里Java開發規范等…… 但對于檔案 似乎相關的資料卻很少，但實際上，不應該把檔案和代碼割裂開來，你可以簡單粗暴地認為檔案其實就是用一種特殊語言書寫的代碼，這種語言就是人類的語言，這么想的話，實際上我們很多在代碼和工程中總結出來的經驗，也可以直接用在檔案中，比如：

• 有統一的規范
• 有版本控制
• 有明確的責任人維護
• 有變更Review機制
• 有問題的反饋和更新機制
• 定期更新
• 有衡量的指標(比如準確性，時效性)

明確你的讀者是誰

寫檔案有一個很常見的錯誤，那就是很多人檔案都是寫給自己看的，這種情況下就會導致你的檔案只有自己或者和你有相似知識背景的人才能看懂，團隊較小時這種問題還好，你們都做著類似的作業，所以也都能看懂檔案，但當團隊逐漸壯大后，問題就會凸顯出來，新人有時候有著和你不同的作業背景，甚至現在都做著不同的作業內容，這時候你之前寫的檔案他們就很難讀懂了，

所以在寫檔案之前請明確你檔案可能的讀者會是哪些人，然后針對他們的特點著重關注如何才能讓他們理解，當然，檔案也不一定要非常嚴肅和完美，只要能向你潛在的讀者說明問題即可， 記住檔案是寫給別人看的，不是給自己看的，

根據專業水平可以大致將讀者分為三種 新手、老手和專家，針對不同水平的人寫作需要有側重點，比如針對新手，你需要重點介紹下里面涉及到的術語和概念，然后詳細講解具體的的實作，相反，針對專家 你可以省去這些額外的資訊，注意，這里沒有嚴格的標準，因為有些文章新手會看，專家也會看， 這里還是需要具體情況具體分析，

另外一種對讀者分類的方式就是根據讀者閱讀檔案的目的來分類，比如有人知道自己遇到了什么問題，就是來找解決方案的，還有一批人只有一個簡單的想法，但不知道具體的問題，舉個例子，以讀資料庫慢為例，前者已經知道資料庫慢可能是因為資料量巨大且沒有加索引，解決方案很簡單 加索引，這時候他可能需要知道的是如何正確地加索引，而后者可能著重關注的是為什么讀資料庫會慢，這時候你可能需要額外重點介紹下資料庫相關的原理，

清晰的分類

檔案大致可以分為以下幾種型別，每種型別也有自己不同的特點和寫作側重點，

參考檔案

參考檔案也是大部分開發人員日常會使用和書寫的檔案，比如我們使用某個框架或者工具，都會有API說明檔案，這就屬于參考類檔案， 它并沒有太多的要求，只要能向讀者展示清楚如何使用即可，但無需向讀者講明具體的實作，

注：參考檔案并不僅限于API檔案，還包括檔案注釋、類注釋、方法注釋，要求都是能準確說明其用法，

設計檔案

很多公司或者團隊在專案開始前都要求有設計檔案，設計是專案實施的第一步，所以在設計檔案書寫的程序中要求盡可能考慮周全，例如該專案的存盤、互動、隱私……

好的設計檔案應該包含以下幾個部分：

1. 設計目標
2. 實作的策略
3. 各種利弊權衡和具體決策
4. 替代方案
5. 各種方案的優缺點

寫設計檔案的程序也你對整個專案做規劃、思考可能出現問題的程序，設計的越詳細、思考的越多，未來遇到問題的可能性就會越小，

引導類檔案

引導類檔案也很常見，一般都是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： 為什么要寫這篇檔案， 你期望讀者讀完后從檔案中獲得什么！

三段式寫作

寫文章一般都會有三個部分，專業寫作者也講究鳳頭、豬肚、豹尾，這三個詞概括出了好文章三部分應有的特點，技術檔案也算是文章的一種，所以一般也都會有這三部分，每個部分有其自己的作用，比如第一部分闡述問題，中間部分介紹具體的解決方案，第三部分總結要點， 但這也并不以為著檔案應該有三個部分，如果檔案內容比較多，可以將其做更細致的拆解，可以適當增加一些冗余的資訊幫助讀者理解檔案內容，雖然很多工程師都討厭冗余 極力追求簡潔，但寫檔案和寫代碼不同，適當的冗余反而可以幫助讀者理解，很簡單，舉個例子，比如寫作中經常舉例子，舉的例子本質上就是冗余資訊，生動的例子肯定是能幫助讀者理解抽象內容的（我想這就是自舉
吧），

結語

目前看到比較好的一個現象就是大家越來越重視檔案了，但和測驗相比 重視的程度還不夠，測驗已經是作業流程中不可或缺的一部分了，而檔案依舊還不是，當然這可能和檔案本身的特性相關，測驗很容易被自動化，也有非常多的客觀指標來評估，檔案卻做不到，首先檔案的書寫需要人手動介入，而檔案的質量也沒有太多客觀的指標評估，提升檔案的數量和質量只能從文化和作業流程上去逐漸改變，

最后總結下本文幾個關鍵點：

• 隨著時間的推移和組織規模的壯大，檔案會越來越重要，
• 檔案也應該是開發流程的一部分，
• 一篇檔案只專注在一件事上，
• 檔案是寫給讀者看的，而不是給你自己看的，