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