一招教你如何寫(xiě)好技術(shù)文檔？
發(fā)布人：xiaomaidashu
時(shí)間：2022-10-18
來(lái)源：工程師
發(fā)布文章
加入技術(shù)交流群
掃碼加入
和技術(shù)大咖面對(duì)面交流
海量資料庫(kù)查詢
很多技術(shù)人自己非常輕視技術(shù)文檔的書(shū)寫(xiě)，然而又時(shí)常抱怨文檔不完善、質(zhì)量差、更新不及時(shí)…
01
文檔的重要性
高質(zhì)量的文檔對(duì)于一個(gè)組織或團(tuán)隊(duì)來(lái)說(shuō)有非常多的益處，比如讓代碼和API更容易理解、錯(cuò)誤更少；
讓團(tuán)隊(duì)成員更專(zhuān)注于目標(biāo)；也可以讓一些手工操作更容易；另外如果有新成員加入的話有文檔也會(huì)讓他們更快融入……
寫(xiě)文檔有比較嚴(yán)重的收益滯后性，不像測(cè)試，你跑一個(gè)測(cè)試case，它能立即告訴你是對(duì)還是錯(cuò)，它的價(jià)值馬上就體現(xiàn)出來(lái)了。
而寫(xiě)一份文檔，隨著時(shí)間的推移，它的價(jià)值才會(huì)逐漸體現(xiàn)出來(lái)。你可能只寫(xiě)一次文檔，將來(lái)它會(huì)被閱讀上百次、上千次，因?yàn)橐环莺玫奈臋n可以在未來(lái)替你向別人回答類(lèi)似下面這些問(wèn)題。
為什么當(dāng)時(shí)是這么決策的？為什么代碼是這樣實(shí)現(xiàn)的？這個(gè)項(xiàng)目里都有哪些概念？……
寫(xiě)文檔同樣對(duì)于寫(xiě)作者也有非常大的好處：
幫你構(gòu)思規(guī)范化API：寫(xiě)文檔的過(guò)程也是你審視你API的過(guò)程，寫(xiě)文檔時(shí)會(huì)讓你思考你API設(shè)計(jì)是否合理，考慮是否周全。如果你沒(méi)法用語(yǔ)言將API描述出來(lái)，那么說(shuō)明你當(dāng)前的API設(shè)計(jì)是不合理的。
文檔也是代碼的另一種展現(xiàn)：比如你兩年后回過(guò)頭來(lái)看你寫(xiě)過(guò)的代碼，如果有注釋和文檔，你可以很快速理解代碼。
讓你的代碼看起來(lái)更專(zhuān)業(yè)：我們都有個(gè)感覺(jué)，只要文檔齊全的API都是設(shè)計(jì)良好的API，雖然這個(gè)感覺(jué)并不完全正確，但這兩者確實(shí)是強(qiáng)相關(guān)的，所以在很多人眼里，文檔的完善度也成為衡量一個(gè)產(chǎn)品專(zhuān)業(yè)度的指標(biāo)。
避免被重復(fù)的問(wèn)題打擾：有些問(wèn)題你只需要寫(xiě)在文檔里，這樣有人來(lái)問(wèn)你的時(shí)候你就可以讓他直接去看文檔了，而不是又給他解釋一遍。
02
為什么大多數(shù)人都不喜歡寫(xiě)文檔？
關(guān)于文檔的重要性，每個(gè)技術(shù)人或多或少都知道一些，但很多人還是沒(méi)有寫(xiě)文檔的習(xí)慣，為什么？
除了上文中提到的文檔的收益滯后性外，還有以下幾點(diǎn)原因：
- 很多工程師習(xí)慣將寫(xiě)代碼和寫(xiě)作割裂開(kāi)，不僅僅是在工作上，而且在思想上就認(rèn)為它們是完全不相關(guān)的兩項(xiàng)工作，這就導(dǎo)致好多人重代碼不重文檔。
- 也有很多工程師認(rèn)為自己不善寫(xiě)作，索性就不寫(xiě)了。這實(shí)際是個(gè)偷懶的借口，寫(xiě)文檔不需要華麗的辭藻、生動(dòng)的語(yǔ)言，你只需要將問(wèn)題講清楚即可。
- 有時(shí)候工具不好用也會(huì)影響的文檔寫(xiě)作。如果沒(méi)有一個(gè)很好的寫(xiě)作工具將寫(xiě)文檔嵌入到開(kāi)發(fā)工作流程中的話，寫(xiě)作確實(shí)會(huì)增加工作的負(fù)擔(dān)。
- 大多數(shù)人將寫(xiě)文檔看做是工作的額外負(fù)擔(dān)。我代碼都沒(méi)時(shí)間寫(xiě)，哪有時(shí)間寫(xiě)文檔！，這其實(shí)是錯(cuò)誤的觀念，文檔雖然前期有投入，但能讓你代碼的后期維護(hù)成本大幅降低，磨刀不誤砍柴工這個(gè)道理相信大家都還是能理解的。
03
如何產(chǎn)出高質(zhì)量文檔？
既然理解了好文檔的重要性，我們?nèi)绾伪ＷC在時(shí)間的長(zhǎng)河中維護(hù)好一份文檔，這里有些相關(guān)的方法論，大家可以參考下。
1.像管理代碼一樣管理文檔
對(duì)于如何寫(xiě)出好代碼，整個(gè)技術(shù)圈已經(jīng)有好多經(jīng)驗(yàn)的總結(jié)了，比如書(shū)籍《重構(gòu)》《代碼簡(jiǎn)潔之道》…… 針對(duì)各種編程語(yǔ)言，也有相關(guān)的規(guī)范，比如國(guó)外的Google C++規(guī)范，國(guó)內(nèi)的阿里Java開(kāi)發(fā)規(guī)范等…… 但對(duì)于文檔 似乎相關(guān)的資料卻很少。
但實(shí)際上，不應(yīng)該把文檔和代碼割裂開(kāi)來(lái)，你可以簡(jiǎn)單粗暴地認(rèn)為文檔其實(shí)就是用一種特殊語(yǔ)言書(shū)寫(xiě)的代碼，這種語(yǔ)言就是人類(lèi)的語(yǔ)言。這么想的話，實(shí)際上我們很多在代碼和工程中總結(jié)出來(lái)的經(jīng)驗(yàn)，也可以直接用在文檔中。
比如：
- 有統(tǒng)一的規(guī)范
- 有版本控制
- 有明確的責(zé)任人維護(hù)
- 有變更Review機(jī)制
- 有問(wèn)題的反饋和更新機(jī)制
- 定期更新
- 有衡量的指標(biāo)(比如準(zhǔn)確性，時(shí)效性)
2.明確你的讀者是誰(shuí)
寫(xiě)文檔有一個(gè)很常見(jiàn)的錯(cuò)誤，那就是很多人文檔都是寫(xiě)給自己看的，這種情況下就會(huì)導(dǎo)致你的文檔只有自己或者和你有相似知識(shí)背景的人才能看懂，團(tuán)隊(duì)較小時(shí)這種問(wèn)題還好，你們都做著類(lèi)似的工作，所以也都能看懂文檔。
但當(dāng)團(tuán)隊(duì)逐漸壯大后，問(wèn)題就會(huì)凸顯出來(lái)，新人有時(shí)候有著和你不同的工作背景，甚至現(xiàn)在都做著不同的工作內(nèi)容，這時(shí)候你之前寫(xiě)的文檔他們就很難讀懂了。
所以在寫(xiě)文檔之前請(qǐng)明確你文檔可能的讀者會(huì)是哪些人，然后針對(duì)他們的特點(diǎn)著重關(guān)注如何才能讓他們理解。
當(dāng)然，文檔也不一定要非常嚴(yán)肅和完美，只要能向你潛在的讀者說(shuō)明問(wèn)題即可。記住文檔是寫(xiě)給別人看的，不是給自己看的。
根據(jù)專(zhuān)業(yè)水平可以大致將讀者分為三種 新手、老手和專(zhuān)家，針對(duì)不同水平的人寫(xiě)作需要有側(cè)重點(diǎn)。
比如針對(duì)新手，你需要重點(diǎn)介紹下里面涉及到的術(shù)語(yǔ)和概念，然后詳細(xì)講解具體的的實(shí)現(xiàn)。相反，針對(duì)專(zhuān)家 你可以省去這些額外的信息。
注意，這里沒(méi)有嚴(yán)格的標(biāo)準(zhǔn)，因?yàn)橛行┪恼滦率謺?huì)看，專(zhuān)家也會(huì)看， 這里還是需要具體情況具體分析。
另外一種對(duì)讀者分類(lèi)的方式就是根據(jù)讀者閱讀文檔的目的來(lái)分類(lèi)，比如有人知道自己遇到了什么問(wèn)題，就是來(lái)找解決方案的。還有一批人只有一個(gè)簡(jiǎn)單的想法，但不知道具體的問(wèn)題。
舉個(gè)例子，以讀數(shù)據(jù)庫(kù)慢為例，前者已經(jīng)知道數(shù)據(jù)庫(kù)慢可能是因?yàn)閿?shù)據(jù)量巨大且沒(méi)有加索引，解決方案很簡(jiǎn)單 加索引，這時(shí)候他可能需要知道的是如何正確地加索引。
而后者可能著重關(guān)注的是為什么讀數(shù)據(jù)庫(kù)會(huì)慢，這時(shí)候你可能需要額外重點(diǎn)介紹下數(shù)據(jù)庫(kù)相關(guān)的原理。
3.清晰的分類(lèi)
文檔大致可以分為以下幾種類(lèi)型，每種類(lèi)型也有自己不同的特點(diǎn)和寫(xiě)作側(cè)重點(diǎn)。
a.參考文檔
參考文檔也是大部分開(kāi)發(fā)人員日常會(huì)使用和書(shū)寫(xiě)的文檔，比如我們使用某個(gè)框架或者工具，都會(huì)有API說(shuō)明文檔，這就屬于參考類(lèi)文檔。它并沒(méi)有太多的要求，只要能向讀者展示清楚如何使用即可，但無(wú)需向讀者講明具體的實(shí)現(xiàn)。
注：參考文檔并不僅限于API文檔，還包括文件注釋、類(lèi)注釋、方法注釋?zhuān)蠖际悄軠?zhǔn)確說(shuō)明其用法。
b.設(shè)計(jì)文檔很多公司或者團(tuán)隊(duì)在項(xiàng)目開(kāi)始前都要求有設(shè)計(jì)文檔，設(shè)計(jì)是項(xiàng)目實(shí)施的第一步，所以在設(shè)計(jì)文檔書(shū)寫(xiě)的過(guò)程中要求盡可能考慮周全，例如該項(xiàng)目的存儲(chǔ)、交互、隱私……
好的設(shè)計(jì)文檔應(yīng)該包含以下幾個(gè)部分：
- 設(shè)計(jì)目標(biāo)
- 實(shí)現(xiàn)的策略
- 各種利弊權(quán)衡和具體決策
- 替代方案
- 各種方案的優(yōu)缺點(diǎn)
寫(xiě)設(shè)計(jì)文檔的過(guò)程也你對(duì)整個(gè)項(xiàng)目做規(guī)劃、思考可能出現(xiàn)問(wèn)題的過(guò)程，設(shè)計(jì)的越詳細(xì)、思考的越多，未來(lái)遇到問(wèn)題的可能性就會(huì)越小。
c.引導(dǎo)類(lèi)文檔引導(dǎo)類(lèi)文檔也很常見(jiàn)，一般都是Step by Step的形式。比如我們?cè)谑褂媚硞€(gè)框架或者工具的時(shí)候，一般都會(huì)有個(gè)引導(dǎo)類(lèi)的文檔一步一步幫助你快速上手。大家寫(xiě)引導(dǎo)類(lèi)文章大家非常容易犯的一個(gè)錯(cuò)誤就是預(yù)設(shè)了很多背景知識(shí)。一般使用文檔都是有開(kāi)發(fā)者寫(xiě)的，他們都非常了解這個(gè)工具的相關(guān)的知識(shí)，所以習(xí)慣性的會(huì)認(rèn)為，啊 這個(gè)知識(shí)點(diǎn)很簡(jiǎn)單 用戶也肯定會(huì)吧，實(shí)際上用戶不一定會(huì)。這本質(zhì)上就是一種認(rèn)知偏差，這種現(xiàn)象在跨團(tuán)隊(duì)協(xié)作 尤其是多端協(xié)作的時(shí)候也非常明顯。
這類(lèi)型的文檔寫(xiě)作中，要求寫(xiě)作者盡可能站在用戶的視角上思考，極力避免出現(xiàn)和用戶的認(rèn)知偏差，力爭(zhēng)每個(gè)步驟做到明確無(wú)歧義，每?jī)蓚€(gè)步驟之間做到緊密銜接。
d.概念性文檔當(dāng)參考文檔無(wú)法解釋清楚某些東西的時(shí)候，就需要概念性文檔了，比如某個(gè)API的具體實(shí)現(xiàn)原理。其主要是為了擴(kuò)充參考文檔，而不是替代參考文檔。有時(shí)候這和參考文檔會(huì)有些內(nèi)容重復(fù)，但主要還是為了更深層次的說(shuō)明某些問(wèn)題、解釋清楚某個(gè)概念。
概念性文檔也是所有文檔中寫(xiě)作最難的，也是被閱讀最少的，所以很多情況下工程師最容易忽視。而且還有另外一個(gè)問(wèn)題，沒(méi)合適的地方放，參考文檔可以寫(xiě)代碼里，落地頁(yè)可以寫(xiě)項(xiàng)目主頁(yè)里，概念性文檔似乎也只能在項(xiàng)目文檔里找個(gè)不起眼的角落存放了。
這類(lèi)文檔的受眾會(huì)比較廣，專(zhuān)家和新手都會(huì)去看。另外，它需要強(qiáng)調(diào)概念清晰明了，因此可能會(huì)犧牲完整性(可以由參考文檔補(bǔ)齊)，也有可能會(huì)犧牲準(zhǔn)確性，這不是說(shuō)一定要犧牲準(zhǔn)確性，只是應(yīng)當(dāng)分清主次，不重要的就沒(méi)必要說(shuō)了。
e.Landing pages(落地頁(yè))Landing pages就先簡(jiǎn)單翻譯成落地頁(yè)了，沒(méi)想到啥恰當(dāng)?shù)姆g詞。比如一個(gè)團(tuán)隊(duì)或者項(xiàng)目的導(dǎo)航頁(yè)，雖然沒(méi)啥具體的內(nèi)容，但應(yīng)該包含其他頁(yè)面的鏈接。比如你新入職一個(gè)團(tuán)隊(duì)，比較成熟的團(tuán)隊(duì)都會(huì)扔給你一個(gè)文檔，這個(gè)文檔里包含常用的工具、文檔鏈接，這就是這個(gè)團(tuán)隊(duì)的落地頁(yè)。落地頁(yè)的問(wèn)題就是隨著時(shí)間的推移，頁(yè)面可能會(huì)變的越來(lái)越亂，而且有些內(nèi)容會(huì)失效，不過(guò)這些問(wèn)題都好解決，做好定期的維護(hù)和整理就行。落地頁(yè)的技術(shù)難度不高，但要求內(nèi)容的有效性、完整性和分類(lèi)清晰。
4.文檔Review在一個(gè)組織內(nèi)，光靠個(gè)人去維護(hù)文檔是不行的，必須得借助群體的智慧。在一個(gè)組織內(nèi)部，文檔的變更也應(yīng)該像代碼的變更一樣，需要被其他人Review，以提前發(fā)現(xiàn)其中的問(wèn)題并提升文檔的質(zhì)量。
如何Review文檔：
- 專(zhuān)業(yè)的視角來(lái)保證準(zhǔn)確性：一般由團(tuán)隊(duì)里比較資深的人負(fù)責(zé)，他們關(guān)注的核心點(diǎn)是文檔寫(xiě)的對(duì)不對(duì)，專(zhuān)不專(zhuān)業(yè)。如果Code Review做的好的話，文檔的Review也屬于Code Review的一部分。
- 讀者視角保證簡(jiǎn)潔性：一般由不熟悉這個(gè)領(lǐng)域的人來(lái)Review，比如團(tuán)隊(duì)的新人，或者文檔的使用者。這部分主要是關(guān)注文檔是否容易被看懂。
- 寫(xiě)作者視角保證一致性：由寫(xiě)作經(jīng)驗(yàn)豐富或者相關(guān)領(lǐng)域比較資深的人承擔(dān)，主要是為了保證文檔前后是否一致，比如對(duì)同一個(gè)專(zhuān)業(yè)術(shù)語(yǔ)的使用和理解是否有歧義。
04
寫(xiě)文檔的哲學(xué)
上面部分站在組織和團(tuán)隊(duì)的視角來(lái)看如何提高文檔質(zhì)量，我們接下來(lái)看看站在個(gè)人寫(xiě)作者的視角上如何寫(xiě)出高質(zhì)量的文檔。
1.5W法則5W法則相信大家已經(jīng)聽(tīng)的多了，分別是Who What When Where Why，這是一個(gè)廣泛被用在各行各業(yè)的法則，寫(xiě)文檔當(dāng)然也能用（5W法則堪稱(chēng)萬(wàn)金油，啥地方都能用）。
WHO：前面已經(jīng)說(shuō)過(guò)了，文檔是寫(xiě)給誰(shuí)看的，讀者是誰(shuí)。WHAT：明確這篇文檔的用途，有時(shí)候，僅僅說(shuō)明文檔的用途和目的就能幫你搭建起整個(gè)文檔的框架。WHEN：明確文檔的創(chuàng)建、Review和更新日期。因?yàn)槲臋n也有時(shí)效性，明確相關(guān)日期可以避免閱讀者踩坑。WHERE：文檔應(yīng)該放在哪！建議一個(gè)組織或者團(tuán)隊(duì)有統(tǒng)一的永久文檔存放地址，并且有版本控制。最好是方便查找、使用和分享。WHY：為什么要寫(xiě)這篇文檔， 你期望讀者讀完后從文檔中獲得什么！
2.三段式寫(xiě)作寫(xiě)文章一般都會(huì)有三個(gè)部分，專(zhuān)業(yè)寫(xiě)作者也講究鳳頭、豬肚、豹尾，這三個(gè)詞概括出了好文章三部分應(yīng)有的特點(diǎn)。技術(shù)文檔也算是文章的一種，所以一般也都會(huì)有這三部分，每個(gè)部分有其自己的作用，比如第一部分闡述問(wèn)題，中間部分介紹具體的解決方案，第三部分總結(jié)要點(diǎn)。但這也并不以為著文檔應(yīng)該有三個(gè)部分，如果文檔內(nèi)容比較多，可以將其做更細(xì)致的拆解，可以適當(dāng)增加一些冗余的信息幫助讀者理解文檔內(nèi)容。雖然很多工程師都討厭冗余 極力追求簡(jiǎn)潔，但寫(xiě)文檔和寫(xiě)代碼不同，適當(dāng)?shù)娜哂喾炊梢詭椭x者理解，很簡(jiǎn)單，舉個(gè)例子，比如寫(xiě)作中經(jīng)常舉例子，舉的例子本質(zhì)上就是冗余信息，生動(dòng)的例子肯定是能幫助讀者理解抽象內(nèi)容的（我想這就是自舉吧）。
05
結(jié)語(yǔ)
目前看到比較好的一個(gè)現(xiàn)象就是大家越來(lái)越重視文檔了，但和測(cè)試相比重視的程度還不夠。
測(cè)試已經(jīng)是工作流程中不可或缺的一部分了，而文檔依舊還不是。當(dāng)然這可能和文檔本身的特性相關(guān)，測(cè)試很容易被自動(dòng)化，也有非常多的客觀指標(biāo)來(lái)評(píng)估。
文檔卻做不到，首先文檔的書(shū)寫(xiě)需要人手動(dòng)介入，而文檔的質(zhì)量也沒(méi)有太多客觀的指標(biāo)評(píng)估，提升文檔的數(shù)量和質(zhì)量只能從文化和工作流程上去逐漸改變。
最后總結(jié)下本文幾個(gè)關(guān)鍵點(diǎn)：
- 隨著時(shí)間的推移和組織規(guī)模的壯大，文檔會(huì)越來(lái)越重要。
- 文檔也應(yīng)該是開(kāi)發(fā)流程的一部分。
- 一篇文檔只專(zhuān)注在一件事上。
- 文檔是寫(xiě)給讀者看的，而不是給你自己看的。
原文地址：https://www.cnblogs.com/xindoo/p/15085988.html
轉(zhuǎn)自公眾號(hào)：嵌入式專(zhuān)欄
*博客內(nèi)容為網(wǎng)友個(gè)人發(fā)布，僅代表博主個(gè)人觀點(diǎn)，如有侵權(quán)請(qǐng)聯(lián)系工作人員刪除。
