如何寫好技術文檔 Software Engineering at Google

前言

文大部分内容翻譯總結自《​​Software Engineering at Google​​》 第10章節 Documentation,一直堅持寫技術文檔，進步一直不大。每次書寫相關工具類或者三方sdk配套文檔，草草寫完，閱讀量也少的可憐。科學學習書寫文檔，做好日常技術積累，定期進行輸出

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

文檔的重要性

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

寫文檔有比較嚴重的收益滞後性，不像測試，你跑一個測試case，它能立即告訴你是對還是錯，它的價值馬上就展現出來了。而寫一份文檔，随着時間的推移，它的價值才會逐漸展現出來。你可能隻寫一次文檔，将來它會被閱讀上百次、上千次，因為一份好的文檔可以在未來替你向别人回答類似下面這些問題。

為什麼當時是這麼決策的？

為什麼代碼是這樣實作的？

這個項目裡都有哪些概念？

……

寫文檔同樣對于寫作者也有非常大的好處：

幫你構思規範化API：寫文檔的過程也是你審視你API的過程，寫文檔時會讓你思考你API設計是否合理，考慮是否周全。如果你沒法用語言将API描述出來，那麼說明你目前的API設計是不合理的。

文檔也是代碼的另一種展現：比如你兩年後回過頭來看你寫過的代碼，如果有注釋和文檔，你可以很快速了解代碼。

讓你的代碼看起來更專業：我們都有個感覺，隻要文檔齊全的API都是設計良好的API，雖然這個感覺并不完全正确，但這兩者确實是強相關的，是以在很多人眼裡，文檔的完善度也成為衡量一個産品專業度的名額。

避免被重複的問題打擾：有些問題你隻需要寫在文檔裡，這樣有人來問你的時候你就可以讓他直接去看文檔了，而不是又給他解釋一遍。

為什麼大多數人都不喜歡寫文檔？

關于文檔的重要性，每個技術人或多或少都知道一些，但很多人還是沒有寫文檔的習慣，為什麼？

除了上文中提到的文檔的收益滞後性外，還有以下幾點原因：

很多工程師習慣将寫代碼和寫作割裂開，不僅僅是在工作上，而且在思想上就認為它們是完全不相關的兩項工作，這就導緻好多人重代碼不重文檔。

也有很多工程師認為自己不善寫作，索性就不寫了。這實際是個偷懶的借口，寫文檔不需要華麗的辭藻、生動的語言，你隻需要将問題講清楚即可。

有時候工具不好用也會影響的文檔寫作。如果沒有一個很好的寫作工具将寫文檔嵌入到開發工作流程中的話，寫作确實會增加工作的負擔。

大多數人将寫文檔看做是工作的額外負擔。我代碼都沒時間寫，哪有時間寫文檔！，這其實是錯誤的觀念，文檔雖然前期有投入，但能讓你代碼的後期維護成本大幅降低，磨刀不誤砍柴工這個道理相信大家都還是能了解的。

如何産出高品質文檔

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

1.像管理代碼一樣管理文檔

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

1. 有統一的規範
2. 有版本控制
3. 有明确的責任人維護
4. 有變更Review機制
5. 有問題的回報和更新機制
6. 定期更新
7. 有衡量的名額(比如準确性，時效性)

2.明确你的讀者是誰

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

是以在寫文檔之前請明确你文檔可能的讀者會是哪些人，然後針對他們的特點着重關注如何才能讓他們了解。當然，文檔也不一定要非常嚴肅和完美，隻要能向你潛在的讀者說明問題即可。記住文檔是寫給别人看的，不是給自己看的。

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

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

3.清晰的分類

文檔大緻可以分為以下幾種類型，每種類型也有自己不同的特點和寫作側重點。

a.參考文檔

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

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

b.設計文檔

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

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

設計目标

實作的政策

各種利弊權衡和具體決策

替代方案

各種方案的優缺點

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

c.引導類文檔

引導類文檔也很常見，一般都是Step by Step的形式。比如我們在使用某個架構或者工具的時候，一般都會有個引導類的文檔一步一步幫助你快速上手。大家寫引導類文章大家非常容易犯的一個錯誤就是預設了很多背景知識。一般使用文檔都是有開發者寫的，他們都非常了解這個工具的相關的知識，是以習慣性的會認為，啊 這個知識點很簡單 使用者也肯定會吧，實際上使用者不一定會。這本質上就是一種認知偏差，這種現象在跨團隊協作 尤其是多端協作的時候也非常明顯。

這類型的文檔寫作中，要求寫作者盡可能站在使用者的視角上思考，極力避免出現和使用者的認知偏差，力争每個步驟做到明确無歧義，每兩個步驟之間做到緊密銜接。

d.概念性文檔

當參考文檔無法解釋清楚某些東西的時候，就需要概念性文檔了，比如某個API的具體實作原理。其主要是為了擴充參考文檔，而不是替代參考文檔。有時候這和參考文檔會有些内容重複，但主要還是為了更深層次的說明某些問題、解釋清楚某個概念。

概念性文檔也是所有文檔中寫作最難的，也是被閱讀最少的，是以很多情況下工程師最容易忽視。而且還有另外一個問題，沒合适的地方放，參考文檔可以寫代碼裡，落地頁可以寫項目首頁裡，概念性文檔似乎也隻能在項目文檔裡找個不起眼的角落存放了。

這類文檔的閱聽人會比較廣，專家和新手都會去看。另外，它需要強調概念清晰明了，是以可能會犧牲完整性(可以由參考文檔補齊)，也有可能會犧牲準确性，這不是說一定要犧牲準确性，隻是應當厘清主次，不重要的就沒必要說了。

e.Landing pages(落地頁)

Landing pages就先簡單翻譯成落地頁了，沒想到啥恰當的翻譯詞。比如一個團隊或者項目的導航頁，雖然沒啥具體的内容，但應該包含其他頁面的連結。比如你新入職一個團隊，比較成熟的團隊都會扔給你一個文檔，這個文檔裡包含常用的工具、文檔連結，這就是這個團隊的落地頁。

落地頁的問題就是随着時間的推移，頁面可能會變的越來越亂，而且有些内容會失效，不過這些問題都好解決，做好定期的維護和整理就行。

落地頁的技術難度不高，但要求内容的有效性、完整性和分類清晰。

4.文檔Review

在一個組織内，光靠個人去維護文檔是不行的，必須得借助群體的智慧。在一個組織内部，文檔的變更也應該像代碼的變更一樣，需要被其他人Review，以提前發現其中的問題并提升文檔的品質。

如何Review文檔：

專業的視角來保證準确性：一般由團隊裡比較資深的人負責，他們關注的核心點是文檔寫的對不對，專不專業。如果Code Review做的好的話，文檔的Review也屬于Code Review的一部分。

讀者視角保證簡潔性：一般由不熟悉這個領域的人來Review，比如團隊的新人，或者文檔的使用者。這部分主要是關注文檔是否容易被看懂。

寫作者視角保證一緻性：由寫作經驗豐富或者相關領域比較資深的人承擔，主要是為了保證文檔前後是否一緻，比如對同一個專業術語的使用和了解是否有歧義。

寫文檔的哲學

上面部分站在組織和團隊的視角來看如何提高文檔品質，我們接下來看看站在個人寫作者的視角上如何寫出高品質的文檔。

1.5W法則

5W法則相信大家已經聽的多了，分别是

Who What When Where Why

，這是一個廣泛被用在各行各業的法則，寫文檔當然也能用（5W法則堪稱萬金油，啥地方都能用）。

WHO：前面已經說過了，文檔是寫給誰看的，讀者是誰。

WHAT：明确這篇文檔的用途，有時候，僅僅說明文檔的用途和目的就能幫你搭建起整個文檔的架構。

WHEN：明确文檔的建立、Review和更新日期。因為文檔也有時效性，明确相關日期可以避免閱讀者踩坑。

WHERE：文檔應該放在哪！建議一個組織或者團隊有統一的永久文檔存放位址，并且有版本控制。最好是友善查找、使用和分享。

WHY：為什麼要寫這篇文檔， 你期望讀者讀完後從文檔中獲得什麼！

2.三段式寫作

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

吧）。

結語

目前看到比較好的一個現象就是大家越來越重視文檔了，但和測試相比重視的程度還不夠。測試已經是工作流程中不可或缺的一部分了，而文檔依舊還不是。當然這可能和文檔本身的特性相關，測試很容易被自動化，也有非常多的客觀名額來評估。