軟件開發(fā)中啄清，為你的軟件系統(tǒng)編寫文檔并不是一件新鮮的事情藏古。幾乎所有人都明白這樣的道理：

你的軟件產(chǎn)品如何優(yōu)秀對用戶來說并不是最重要的晨继，因?yàn)槟愕奈臋n如果不夠優(yōu)秀烟阐，用戶不會使用它搬俊！即便用戶在某些情況下不得不使用你的產(chǎn)品紊扬，沒有好的文檔，用戶無法高效使用或者以錯誤的方式使用你的產(chǎn)品唉擂。

不幸的是餐屎，鮮少能見到關(guān)于如何正確組織技術(shù)文檔的實(shí)踐及方法論。團(tuán)隊(duì)工作中玩祟，編寫文檔仍面臨挑戰(zhàn)腹缩。

倉促地開始和結(jié)束

編寫技術(shù)文檔這個任務(wù)看起來總是：優(yōu)先級不夠高，特別花時間并且沒有立竿見影的正反饋空扎！于是文檔編寫被一推再推藏鹊，直至在某些時刻不得不做，比如新人要上項(xiàng)目了转锈，我的開源產(chǎn)品要發(fā)布了盘寡，才震驚地發(fā)現(xiàn)我竟沒有文檔。文檔最后被隨意編寫撮慨，以至于完成后就被徹底忽視竿痰。隨著系統(tǒng)的演進(jìn)脆粥，這些文檔慢慢脫節(jié)，變成謊言影涉！這個論斷乍一看如此地荒謬变隔，可是卻在我身邊常常發(fā)生。

混亂的結(jié)構(gòu)

如同代碼編寫一樣蟹倾，混亂的結(jié)構(gòu)是相當(dāng)致命的匣缘。我們能使用類似于technical-writing-template這樣，基于模板約定的方式使得單篇文章的質(zhì)量達(dá)到一定的水準(zhǔn)喊式。然而在復(fù)雜的軟件系統(tǒng)中孵户，高質(zhì)量的單篇顯然是杯水車薪的。事實(shí)上岔留，眾多優(yōu)秀的軟件產(chǎn)品它們基本都具備恰到好處的文檔夏哭，清晰的結(jié)構(gòu)使得初學(xué)者和長期用戶讀起來都毫不費(fèi)力。我以為献联，未能使文檔免于混亂的原因有以下幾點(diǎn)：

1. 文檔是由多個人編寫的竖配。《解析極限編程》中描述一個XP團(tuán)隊(duì)中會有“文檔撰寫員”的角色里逆。即便敏捷實(shí)踐大行其道的今天进胯，敏捷團(tuán)隊(duì)中，不論是成熟的“角色是帽子”原押，還是傳統(tǒng)的“角色是崗位”胁镐，都大概很少會見到“文檔撰寫員”這一角色。文檔是由不同的人編寫不同的部分诸衔，再組合而成的盯漂，混亂是自然而然的結(jié)果。
2. 缺少對抗混亂的模式笨农。不同于軟件編寫就缆，我們有架構(gòu)風(fēng)格這樣深入人心的默認(rèn)約定。甚至有C4 model來可視化軟件架構(gòu)谒亦，幫助團(tuán)隊(duì)保持一致的認(rèn)知竭宰，并使架構(gòu)有序地演進(jìn)。文檔的編寫除了本文將要介紹的文檔象限之外份招，并未發(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)化文檔不僅僅是當(dāng)前最為主流的文檔組織方式巩步，在可預(yù)見的未來也會如此旁赊。

保持清晰的結(jié)構(gòu)絕非易事，筆者深感幸運(yùn)能夠看到一種確保正確生成結(jié)構(gòu)化文檔的模式：文檔象限椅野。

在一個坐標(biāo)系下终畅，劃分象限的兩條軸描述了文檔所具有的屬性，橫軸描述文檔的使用場景是偏于工作的還是偏于學(xué)習(xí)的竟闪，縱軸描述文檔是偏于理論的還是偏于實(shí)踐的离福。這四個象限分別是tutorials，how-to guides炼蛤，reference和explanation：

文檔象限將其內(nèi)容呈現(xiàn)方式劃定了明確的邊界妖爷，讓文檔看起來簡單明了，更適合對外輸出理朋，幫助用戶快速上手絮识。

圖譜化文檔

結(jié)構(gòu)化文檔之外似乎還存在另一種文檔組織方式：圖譜化，并且初具影響力嗽上。 很多時候次舌，為了保持文章的簡潔和內(nèi)聚，我喜歡使用鏈接文字將一個相關(guān)概念指向別處兽愤。一旦順著鏈接深入幾層彼念，就會發(fā)現(xiàn)文檔所承載的知識很快組成一張大網(wǎng)。知識圖譜一詞簡直恰如其分浅萧。自2012年谷歌知識圖譜發(fā)布以來逐沙，知識圖譜的主要用武之地仍在搜索引擎，文獻(xiàn)檢索領(lǐng)域惯殊。有諸如logseq這樣的產(chǎn)品另辟蹊徑酱吝，強(qiáng)化知識之間的鏈接也殖，以圖譜化的方式組織文檔土思。其主要使用方式是關(guān)鍵字檢索加上相關(guān)內(nèi)容（linked reference）的跳轉(zhuǎn)。

在使用logseq的過程中忆嗜，我發(fā)現(xiàn)這種方式更契合人類在大腦中構(gòu)建的知識模型己儒，有利于深刻又全面地理解問題。這與盧曼的《卡片筆記寫作法》有異曲同工之妙捆毫。

筆者以為闪湾，圖譜化的文檔組織方式在團(tuán)隊(duì)中更適合知識的生產(chǎn)和管理，即作為團(tuán)隊(duì)的知識庫绩卤。原因與其主要使用方式有關(guān)途样。盡管我認(rèn)為關(guān)鍵字檢索不失為一種高效的方式江醇，但是給新用戶的檢索能力提出了挑戰(zhàn)。

選型參考

當(dāng)你開始著手構(gòu)建文檔的時候何暇，即便不作任何考量陶夜，也要借助一些文檔工具甚至協(xié)作平臺來保存你編寫的文檔。筆者了解到一些常用的文檔工具：

文檔生成工具：

• sphinx
• docusaurus

文檔托管與協(xié)同：

• google doc
• confluence

圖譜化文檔工具：

• logseq

了解到這些文檔構(gòu)建方式和工具有什么用呢裆站？這個世界大概不存在一個完美的軟件工具或者系統(tǒng)使得所有的個性化需求都被滿足条辟。當(dāng)你為了協(xié)同編輯選擇了google doc，將不得不面對大量的樣式調(diào)整工作宏胯。當(dāng)你使用logseq作為團(tuán)隊(duì)內(nèi)部的知識庫羽嫡，其特有的文檔標(biāo)記格式使其難以遷移到其他的工具里。這真讓人沮喪肩袍！于是乎杭棵，構(gòu)建文檔也要進(jìn)行類似技術(shù)選型的工作，確定一個合適的方案氛赐。這意味著要在艱難的權(quán)衡之下颜屠，選擇能滿足需求的方案，其優(yōu)點(diǎn)仍令人振奮鹰祸，其缺點(diǎn)還可以忍受甫窟。

值得注意的是，具備能寫文檔這樣的功能并非唯一的需求蛙婴，選擇方案時我們似乎更看重功能以外的重要特性粗井。沒錯，文檔構(gòu)建也該滿足可預(yù)見的非功能性需求：

1. 可移植性：在可預(yù)見的未來街图，是否需要將文檔遷移到另一個環(huán)境浇衬？
2. 可用性：用戶體驗(yàn)與易用性，協(xié)作能力餐济，國際化
3. 合規(guī)性
4. 可訪問性：僅內(nèi)部網(wǎng)絡(luò)有效耘擂？完全公開還是要通過授權(quán)鑒權(quán)？
5. 存檔：文檔如何被變更絮姆，保存醉冤，備份？
6. ...

令人激動的文檔構(gòu)建方案

sphinx + 文檔象限 + Git

利用文檔象限組織內(nèi)容篙悯，利用Github等托管平臺保存蚁阳，sphinx將其生成為電子書發(fā)布，或者生成HTML進(jìn)行私有化部署鸽照。

• 優(yōu)點(diǎn)
  • 良好的國際化支持
  • 極高的靈活性
  • sphinx高度可配置螺捐，擁有成熟的生態(tài)
  • 文檔托管及私有化部署具有眾多的代替選項(xiàng)
  • 只依賴Python運(yùn)行環(huán)境，具有極高的可移植性，可以隨軟件版本迭代一起更新定血，維護(hù)赔癌，部署，納入迭代管理
• 缺點(diǎn)
  • 要求文檔的貢獻(xiàn)者熟悉兩種技術(shù)：Git 和 markdown

:memo: Note: 這里有一個How-to guide: 于sphinx上實(shí)踐文檔象限

logseq

使用loqseq作為知識庫澜沟，利用Github等托管平臺保存文檔

• 優(yōu)點(diǎn)
  • 能夠以極低的成本構(gòu)建知識圖譜届榄，作為知識庫
  • 使用方式是關(guān)鍵字檢索和關(guān)聯(lián)內(nèi)容跳轉(zhuǎn)，這是一種讓人更容易聚焦于思考的交互方式
• 缺點(diǎn)
  • 使用方式是關(guān)鍵字檢索和關(guān)聯(lián)內(nèi)容跳轉(zhuǎn)倔喂，并不適合新手快速上手
  • 需要每一個用戶安裝logseq的客戶端
  • 要求文檔的貢獻(xiàn)者熟悉兩種技術(shù)：Git 和 markdown
  • 難以對外發(fā)布內(nèi)容

google doc/confluence + 文檔象限

• 優(yōu)點(diǎn)
  • 多人協(xié)同
  • 內(nèi)建的鑒權(quán)授權(quán)铝条，支持單點(diǎn)登錄（sso）
  • 大眾化的產(chǎn)品，易用性好
• 缺點(diǎn)
  • 需要手動管理存檔備份席噩，容易造成混亂
  • 可移植性差

總結(jié)

慎重地審視這些方案各自的優(yōu)缺點(diǎn)后班缰，我發(fā)現(xiàn)采用結(jié)構(gòu)化的文檔組織方式時，文檔象限總是有用武之地悼枢，似乎能夠保證我們生成“不太壞”的文檔埠忘。同時，筆者建議慎重選擇圖譜化文檔馒索，你可能并沒有做好因文檔改變自己工作習(xí)慣的準(zhǔn)備莹妒，你可能還需要同時維護(hù)一份結(jié)構(gòu)化文檔。

文/Thoughtworks 蔡正鋒
原文鏈接：如何編寫技術(shù)文檔绰上？-Thoughtworks洞見