如何編寫技術文檔？
作者 | 蔡正鋒
軟件開發中，為你的軟件系統編寫文檔并不是一件新鮮的事情。幾乎所有人都明白這樣的道理：
你的軟件產品如何優秀對用戶來說并不是最重要的，因為你的文檔如果不夠優秀，用戶不會使用它！即便用戶在某些情況下不得不使用你的產品，沒有好的文檔，用戶無法高效使用或者以錯誤的方式使用你的產品。
不幸的是，鮮少能見到關于如何正確組織技術文檔的實踐及方法論。團隊工作中，編寫文檔仍面臨挑戰。
面臨的挑戰
倉促地開始和結束
編寫技術文檔這個任務看起來總是：優先級不夠高，特別花時間并且沒有立竿見影的正反饋！于是文檔編寫被一推再推，直至在某些時刻不得不做，比如新人要上項目了，我的開源產品要發布了，才震驚地發現我竟沒有文檔。文檔最后被隨意編寫，以至于完成后就被徹底忽視。隨著系統的演進，這些文檔慢慢脫節，變成謊言！這個論斷乍一看如此地荒謬，可是卻在我身邊常常發生。
混亂的結構
如同代碼編寫一樣，混亂的結構是相當致命的。我們能使用類似于technical-writing-template這樣，基于模板約定的方式使得單篇文章的質量達到一定的水準。然而在復雜的軟件系統中，高質量的單篇顯然是杯水車薪的。事實上，眾多優秀的軟件產品它們基本都具備恰到好處的文檔，清晰的結構使得初學者和長期用戶讀起來都毫不費力。我以為，未能使文檔免于混亂的原因有以下幾點：
- 文檔是由多個人編寫的。《解析極限編程》中描述一個XP團隊中會有“文檔撰寫員”的角色。即便敏捷實踐大行其道的今天，敏捷團隊中，不論是成熟的“角色是帽子”，還是傳統的“角色是崗位”，都大概很少會見到“文檔撰寫員”這一角色。文檔是由不同的人編寫不同的部分，再組合而成的，混亂是自然而然的結果。
- 缺少對抗混亂的模式。不同于軟件編寫，我們有架構風格這樣深入人心的默認約定。甚至有C4 model來可視化軟件架構，幫助團隊保持一致的認知，并使架構有序地演進。文檔的編寫除了本文將要介紹的文檔象限之外，并未發現任何一種有較大影響力的編寫模式。
兩種組織方式
結構化文檔
通過觀察優秀技術文檔的組織形式，諸如unix manual、Spring boot或者React，你會發現它們都是結構化的。主要使用方式是按照索引查閱感興趣的內容。
通常，所謂編寫技術文檔，基本意味著編寫類似的結構化文檔。結構化文檔不僅僅是當前最為主流的文檔組織方式，在可預見的未來也會如此。
保持清晰的結構絕非易事，筆者深感幸運能夠看到一種確保正確生成結構化文檔的模式：文檔象限。
在一個坐標系下，劃分象限的兩條軸描述了文檔所具有的屬性，橫軸描述文檔的使用場景是偏于工作的還是偏于學習的，縱軸描述文檔是偏于理論的還是偏于實踐的。這四個象限分別是tutorials，how-to guides，reference和explanation：
圖片
圖片
文檔象限將其內容呈現方式劃定了明確的邊界，讓文檔看起來簡單明了，更適合對外輸出，幫助用戶快速上手。
圖譜化文檔
結構化文檔之外似乎還存在另一種文檔組織方式：圖譜化，并且初具影響力。很多時候，為了保持文章的簡潔和內聚，我喜歡使用鏈接文字將一個相關概念指向別處。一旦順著鏈接深入幾層，就會發現文檔所承載的知識很快組成一張大網。知識圖譜一詞簡直恰如其分。自2012年谷歌知識圖譜發布以來，知識圖譜的主要用武之地仍在搜索引擎，文獻檢索領域。有諸如logseq這樣的產品另辟蹊徑，強化知識之間的鏈接，以圖譜化的方式組織文檔。其主要使用方式是關鍵字檢索加上相關內容（linked reference）的跳轉。
在使用logseq的過程中，我發現這種方式更契合人類在大腦中構建的知識模型，有利于深刻又全面地理解問題。這與盧曼的《卡片筆記寫作法》有異曲同工之妙。
筆者以為，圖譜化的文檔組織方式在團隊中更適合知識的生產和管理，即作為團隊的知識庫。原因與其主要使用方式有關。盡管我認為關鍵字檢索不失為一種高效的方式，但是給新用戶的檢索能力提出了挑戰。
選型參考
當你開始著手構建文檔的時候，即便不作任何考量，也要借助一些文檔工具甚至協作平臺來保存你編寫的文檔。筆者了解到一些常用的文檔工具：
文檔生成工具：
- sphinx
- docusaurus
文檔托管與協同：
- google doc
- confluence
圖譜化文檔工具：
- logseq
了解到這些文檔構建方式和工具有什么用呢？這個世界大概不存在一個完美的軟件工具或者系統使得所有的個性化需求都被滿足。當你為了協同編輯選擇了google doc，將不得不面對大量的樣式調整工作。當你使用logseq作為團隊內部的知識庫，其特有的文檔標記格式使其難以遷移到其他的工具里。這真讓人沮喪！于是乎，構建文檔也要進行類似技術選型的工作，確定一個合適的方案。這意味著要在艱難的權衡之下，選擇能滿足需求的方案，其優點仍令人振奮，其缺點還可以忍受。
值得注意的是，具備能寫文檔這樣的功能并非唯一的需求，選擇方案時我們似乎更看重功能以外的重要特性。沒錯，文檔構建也該滿足可預見的非功能性需求：
- 可移植性：在可預見的未來，是否需要將文檔遷移到另一個環境？
- 可用性：用戶體驗與易用性，協作能力，國際化
- 合規性
- 可訪問性：僅內部網絡有效？完全公開還是要通過授權鑒權？
- 存檔：文檔如何被變更，保存，備份？
- ...
令人激動的文檔構建方案
sphinx + 文檔象限 + Git
利用文檔象限組織內容，利用Github等托管平臺保存，sphinx將其生成為電子書發布，或者生成HTML進行私有化部署。
(1) 優點
- 良好的國際化支持
- 極高的靈活性
- sphinx高度可配置，擁有成熟的生態
- 文檔托管及私有化部署具有眾多的代替選項
- 只依賴Python運行環境，具有極高的可移植性，可以隨軟件版本迭代一起更新，維護，部署，納入迭代管理
(2) 缺點
- 要求文檔的貢獻者熟悉兩種技術：Git 和 markdown
:memo: Note: 這里有一個How-to guide: 于sphinx上實踐文檔象限
logseq
使用loqseq作為知識庫，利用Github等托管平臺保存文檔
(1) 優點
- 能夠以極低的成本構建知識圖譜，作為知識庫
- 使用方式是關鍵字檢索和關聯內容跳轉，這是一種讓人更容易聚焦于思考的交互方式
(2) 缺點
- 使用方式是關鍵字檢索和關聯內容跳轉，并不適合新手快速上手
- 需要每一個用戶安裝logseq的客戶端
- 要求文檔的貢獻者熟悉兩種技術：Git 和 markdown
- 難以對外發布內容
google doc/confluence + 文檔象限
(1) 優點
- 多人協同
- 內建的鑒權授權，支持單點登錄（sso）
- 大眾化的產品，易用性好
(2) 缺點
- 需要手動管理存檔備份，容易造成混亂
- 可移植性差
總結
慎重地審視這些方案各自的優缺點后，我發現采用結構化的文檔組織方式時，文檔象限總是有用武之地，似乎能夠保證我們生成“不太壞”的文檔。同時，筆者建議慎重選擇圖譜化文檔，你可能并沒有做好因文檔改變自己工作習慣的準備，你可能還需要同時維護一份結構化文檔。
