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