為軟件系統(tǒng)編寫文檔在軟件開發(fā)中并不是什么新鮮事。幾乎每個人都明白這個原則:

你的軟件產(chǎn)品對用戶來說有多優(yōu)秀并不是最重要的,因為如果你的文檔不夠好,用戶就不會使用它!即使在某些情況下用戶不得不使用你的產(chǎn)品,他們也需要好的文檔才能高效使用,否則可能會誤用你的產(chǎn)品。

不幸的是,幾乎沒有正確組織技術(shù)文檔的實踐和方法論。在團(tuán)隊合作中,編寫文檔仍然面臨挑戰(zhàn)。

倉促開始和結(jié)束

編寫技術(shù)文檔的任務(wù)似乎總是優(yōu)先級很低:它需要大量時間,而且沒有立即的正面反饋!所以文檔編寫一再推遲,直到某個時候不得不完成,比如新團(tuán)隊成員加入項目或我的開源產(chǎn)品即將發(fā)布時。只有到那時我才驚恐地意識到我沒有文檔。文檔最終被草草編寫,以至于完成后完全被忽視。隨著系統(tǒng)的發(fā)展,這些文檔逐漸脫節(jié)并變成謊言!這種說法乍一看似乎很荒謬,但在我周圍經(jīng)常發(fā)生。

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

就像編寫代碼一樣,混亂的結(jié)構(gòu)可能相當(dāng)致命。我們可以使用類似 technical-writing-template 的東西來確保單篇文章的質(zhì)量基于模板約定達(dá)到一定標(biāo)準(zhǔn)。然而,在復(fù)雜的軟件系統(tǒng)中,高質(zhì)量的單篇文章是不夠的。許多優(yōu)秀的軟件產(chǎn)品都有適當(dāng)結(jié)構(gòu)化的文檔,讓初學(xué)者和長期用戶都能輕松閱讀。我認(rèn)為文檔無法擺脫混亂有幾個原因:

1. 文檔由多人編寫?！短剿鳂O限編程》描述了XP團(tuán)隊中"文檔編寫者"的角色。盡管如今敏捷實踐盛行,但在敏捷團(tuán)隊中,無論是成熟的"角色即帽子"概念還是傳統(tǒng)的"角色即職位"概念,"文檔編寫者"的角色可能很少見。文檔由不同的人為不同的部分編寫,然后組合在一起,自然會導(dǎo)致混亂。
2. 缺乏對抗混亂的模式。與軟件編寫不同,我們有深入人心的默認(rèn)約定作為架構(gòu)風(fēng)格。甚至還有C4模型來可視化軟件架構(gòu),幫助團(tuán)隊保持一致理解,并允許架構(gòu)有序演變。除了本文將介紹的文檔象限外,未發(fā)現(xiàn)其他有影響力的寫作模式。

兩種組織方法

1. 結(jié)構(gòu)化文檔

通過觀察優(yōu)秀技術(shù)文檔的組織結(jié)構(gòu),如Unix手冊、Spring Boot或React,你會發(fā)現(xiàn)它們都是結(jié)構(gòu)化的。主要用法是根據(jù)索引瀏覽感興趣的內(nèi)容。

一般來說,編寫技術(shù)文檔基本上意味著編寫類似的結(jié)構(gòu)化文檔。結(jié)構(gòu)化文檔不僅是目前最主流的文檔組織方式,在可預(yù)見的未來也將如此。

保持清晰的結(jié)構(gòu)絕非易事。作者很幸運(yùn)地看到了一種確保正確生成結(jié)構(gòu)化文檔的模式:文檔象限。

在坐標(biāo)系中,將象限分為兩個軸描述文檔的屬性。橫軸描述文檔的使用場景是傾向于工作還是學(xué)習(xí),縱軸描述是傾向于理論還是實踐。這四個象限分別是教程、操作指南、參考和解釋:

圖片

文檔象限為其內(nèi)容的呈現(xiàn)定義了明確的界限,使文檔看起來簡單易懂,更適合對外輸出,并幫助用戶快速入門。

2. 圖形化文檔

除了結(jié)構(gòu)化文檔之外,似乎還有另一種組織文檔的方式:基于圖形,并且正在獲得影響力。通常,為了保持文章的簡潔性和連貫性,我喜歡使用鏈接文本指出其他地方的相關(guān)概念。一旦你深入幾層鏈接,你會發(fā)現(xiàn)文檔承載的知識很快形成一個大網(wǎng)絡(luò)。"知識圖譜"這個術(shù)語恰如其分。自2012年Google知識圖譜發(fā)布以來,知識圖譜的主要應(yīng)用仍在搜索引擎和文獻(xiàn)檢索領(lǐng)域。像logseq這樣的產(chǎn)品采取了不同的方法,通過加強(qiáng)知識之間的聯(lián)系,以圖形化方式組織文檔。其主要用法涉及關(guān)鍵詞搜索結(jié)合跳轉(zhuǎn)到相關(guān)內(nèi)容(鏈接引用)。

在使用 logseq 時,我發(fā)現(xiàn)這種方法更符合人類在大腦中構(gòu)建知識模型的方式,有助于深入全面地理解問題。這與Luhmann的"Zettelkasten方法"產(chǎn)生共鳴。

我認(rèn)為,基于圖形的文檔組織更適合作為團(tuán)隊的知識庫,用于團(tuán)隊內(nèi)部的知識生產(chǎn)和管理。這與其主要操作模式有關(guān)。雖然我認(rèn)為關(guān)鍵詞搜索是一種有效的方法,但它對新用戶的搜索能力提出了挑戰(zhàn)。

選擇參考

當(dāng)你開始構(gòu)建文檔時,即使沒有任何考慮,你也應(yīng)該使用一些文檔工具或協(xié)作平臺來保存你編寫的文檔。我了解一些常用的文檔工具:

文檔生成工具:

• sphinx
• docusaurus

文檔托管和協(xié)作:

• Google Docs
• Confluence

圖形化文檔工具:

• logseq

這些文檔構(gòu)建方法和工具有什么用途?世界上可能沒有完美的軟件工具或系統(tǒng)能滿足所有個性化需求。當(dāng)你選擇Google Docs進(jìn)行協(xié)作編輯時,你將不得不處理大量樣式調(diào)整。當(dāng)你使用Logseq作為團(tuán)隊的內(nèi)部知識庫時,其獨(dú)特的文檔標(biāo)記格式使得遷移到其他工具變得困難。這令人沮喪!因此,構(gòu)建文檔也需要類似的技術(shù)決策工作來確定適合的解決方案。這意味著在困難的權(quán)衡中做出選擇,選擇一個滿足要求的解決方案,其優(yōu)點仍然鼓舞人心,而缺點是可以容忍的。

值得注意的是,具備編寫文檔的能力并不是唯一要求;在選擇解決方案時,我們似乎更重視功能之外的重要特性。是的,文檔構(gòu)建也應(yīng)該滿足可預(yù)見的非功能性需求:

• 可移植性:在可預(yù)見的未來,是否需要將文檔遷移到另一個環(huán)境?
• 可用性:用戶體驗和易用性、協(xié)作能力、國際化。
• 合規(guī)性
• 可訪問性:僅在內(nèi)部網(wǎng)絡(luò)有效?完全公開還是需要授權(quán)和認(rèn)證?
• 存檔:文檔如何更改、保存和備份?
• ...

令人興奮的文檔構(gòu)建解決方案

1. sphinx + Document Zenith + Git

使用Document Zenith組織內(nèi)容,保存在Github等托管平臺上,并使用Sphinx生成電子書進(jìn)行發(fā)布,或生成HTML進(jìn)行私有部署。

優(yōu)點:

• 良好的國際化支持
• 高度靈活性
• Sphinx高度可配置,生態(tài)系統(tǒng)成熟
• 文檔托管和私有部署有多種替代選擇
• 只依賴Python運(yùn)行環(huán)境,可移植性高,可以隨軟件版本迭代更新、維護(hù)、部署,并納入迭代管理

缺點:

• 文檔貢獻(xiàn)者需要熟悉兩種技術(shù):Git和markdown

2. logseq

使用logseq作為知識庫,并將文檔保存在Github等托管平臺上。

優(yōu)點:

• 可以以極低成本構(gòu)建知識圖譜,作為知識庫
• 使用方式涉及關(guān)鍵詞搜索和跳轉(zhuǎn)到相關(guān)內(nèi)容,這種交互方式更容易讓人專注于思考

缺點:

• 使用方式涉及關(guān)鍵詞搜索和跳轉(zhuǎn)到相關(guān)內(nèi)容,不適合初學(xué)者快速入門
• 需要每個用戶安裝Logseq客戶端
• 貢獻(xiàn)者需要熟悉兩種技術(shù):Git和markdown
• 難以對外發(fā)布內(nèi)容

3. Google Docs/Confluence + 文檔管理

優(yōu)點:

• 多用戶協(xié)作
• 內(nèi)置認(rèn)證和授權(quán)支持單點登錄(SSO)
• 流行產(chǎn)品,易用性好

缺點:

• 需要手動管理存檔和備份,容易導(dǎo)致混亂
• 可移植性差