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

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

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

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

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

倉(cāng)促開始和結(jié)束

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

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

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

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

兩種組織方法

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

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

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

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

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

圖片

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

圖形化文檔

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

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

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

選擇參考

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

文檔生成工具:

sphinx
docusaurus

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

Google Docs
Confluence

圖形化文檔工具:

logseq

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

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