我們一起聊聊如何編寫技術(shù)文檔

作者：dev 2024-09-09 00:00:00

編寫技術(shù)文檔的任務(wù)似乎總是優(yōu)先級很低:它需要大量時間,而且沒有立即的正面反饋!所以文檔編寫一再推遲,直到某個時候不得不完成,比如新團(tuán)隊成員加入項目或我的開源產(chǎn)品即將發(fā)布時。

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

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

不幸的是,幾乎沒有正確組織技術(shù)文檔的實(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)為文檔無法擺脫混亂有幾個原因:

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

兩種組織方法

結(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í),縱軸描述是傾向于理論還是實(shí)踐。這四個象限分別是教程、操作指南、參考和解釋:

圖片

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

圖形化文檔

除了結(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)點(diǎn)仍然鼓舞人心,而缺點(diǎn)是可以容忍的。

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