[[417622]]

圖片來自 包圖網(wǎng)

很多技術(shù)人自己非常輕視技術(shù)文檔的書寫，然而又時(shí)常抱怨文檔不完善、質(zhì)量差、更新不及時(shí)……

這種在程序猿間普遍存在的矛盾甚至已經(jīng)演變成了一個段子。

[[417623]]

1、文檔的重要性

高質(zhì)量的文檔對于一個組織或團(tuán)隊(duì)來說有非常多的益處，比如讓代碼和 API 更容易理解、錯誤更少;讓團(tuán)隊(duì)成員更專注于目標(biāo);也可以讓一些手工操作更容易;另外如果有新成員加入的話有文檔也會讓他們更快融入……

寫文檔有比較嚴(yán)重的收益滯后性，不像測試，你跑一個測試 case，它能立即告訴你是對還是錯，它的價(jià)值馬上就體現(xiàn)出來了。

而寫一份文檔，隨著時(shí)間的推移，它的價(jià)值才會逐漸體現(xiàn)出來。你可能只寫一次文檔，將來它會被閱讀上百次、上千次。

因?yàn)橐环莺玫奈臋n可以在未來替你向別人回答類似下面這些問題：

• 為什么當(dāng)時(shí)是這么決策的?
• 為什么代碼是這樣實(shí)現(xiàn)的?
• 這個項(xiàng)目里都有哪些概念?
• ……

寫文檔同樣對于寫作者也有非常大的收益：

• 幫你構(gòu)思規(guī)范化 API：寫文檔的過程也是你審視你 API 的過程，寫文檔時(shí)會讓你思考你 API 設(shè)計(jì)是否合理，考慮是否周全。如果你沒法用語言將 API 描述出來，那么說明你當(dāng)前的 API 設(shè)計(jì)是不合理的。
• 文檔也是代碼的另一種展現(xiàn)：比如你兩年后回過頭來看你寫過的代碼，如果有注釋和文檔，你可以很快速理解代碼。
• 讓你的代碼看起來更專業(yè)：我們都有個感覺，只要文檔齊全的 API 都是設(shè)計(jì)良好的 API，雖然這個感覺并不完全正確，但這兩者確實(shí)是強(qiáng)相關(guān)的，所以在很多人眼里，文檔的完善度也成為衡量一個產(chǎn)品專業(yè)度的指標(biāo)。
• 避免被重復(fù)的問題打擾：有些問題你只需要寫在文檔里，這樣有人來問你的時(shí)候你就可以讓他直接去看文檔了，而不是又給他解釋一遍。

2、為什么大多數(shù)人都不喜歡寫文檔

關(guān)于文檔的重要性，每個技術(shù)人或多或少都知道一些，但很多人還是沒有寫文檔的習(xí)慣，為什么?

除了上文中提到的文檔的收益滯后性外，還有以下幾點(diǎn)原因：

• 很多工程師習(xí)慣將寫代碼和寫作割裂開，不僅僅是在工作上，而且在思想上就認(rèn)為它們是完全不相關(guān)的兩項(xiàng)工作，這就導(dǎo)致好多人重代碼不重文檔。
• 也有很多工程師認(rèn)為自己不善寫作，索性就不寫了。這實(shí)際是個偷懶的借口，寫文檔不需要華麗的辭藻、生動的語言，你只需要將問題講清楚即可。
• 有時(shí)候工具不好用也會影響的文檔寫作。如果沒有一個很好的寫作工具將寫文檔嵌入到開發(fā)工作流程中的話，寫作確實(shí)會增加工作的負(fù)擔(dān)。
• 大多數(shù)人將寫文檔看做是工作的額外負(fù)擔(dān)。 我代碼都沒時(shí)間寫，哪有時(shí)間寫文檔!這其實(shí)是錯誤的觀念，文檔雖然前期有投入，但能讓你代碼的后期維護(hù)成本大幅降低，磨刀不誤砍柴工這個道理相信大家都還是能理解的。

3、如何產(chǎn)出高質(zhì)量文檔

既然理解了好文檔的重要性，我們?nèi)绾伪ＷC在時(shí)間的長河中維護(hù)好一份文檔，這里有些相關(guān)的方法論，大家可以參考下。

①像管理代碼一樣管理文檔

對于如何寫出好代碼，整個技術(shù)圈已經(jīng)有好多經(jīng)驗(yàn)的總結(jié)了，比如書籍《重構(gòu)》《代碼簡潔之道》……

針對各種編程語言，也有相關(guān)的規(guī)范，比如國外的 Google C++ 規(guī)范，國內(nèi)的阿里 Java 開發(fā)規(guī)范等……但對于文檔似乎相關(guān)的資料卻很少。

但實(shí)際上，不應(yīng)該把文檔和代碼割裂開來，你可以簡單粗暴地認(rèn)為文檔其實(shí)就是用一種特殊語言書寫的代碼，這種語言就是人類的語言。

這么想的話，實(shí)際上我們很多在代碼和工程中總結(jié)出來的經(jīng)驗(yàn)，也可以直接用在文檔中。

比如：

• 有統(tǒng)一的規(guī)范
• 有版本控制
• 有明確的責(zé)任人維護(hù)
• 有變更 Review 機(jī)制
• 有問題的反饋和更新機(jī)制
• 定期更新
• 有衡量的指標(biāo)(比如準(zhǔn)確性，時(shí)效性)

②明確你的讀者是誰

寫文檔有一個很常見的錯誤，那就是很多人文檔都是寫給自己看的，這種情況下就會導(dǎo)致你的文檔只有自己或者和你有相似知識背景的人才能看懂，團(tuán)隊(duì)較小時(shí)這種問題還好，你們都做著類似的工作，所以也都能看懂文檔。

但當(dāng)團(tuán)隊(duì)逐漸壯大后，問題就會凸顯出來，新人有時(shí)候有著和你不同的工作背景，甚至現(xiàn)在都做著不同的工作內(nèi)容，這時(shí)候你之前寫的文檔他們就很難讀懂了。

所以在寫文檔之前請明確你文檔可能的讀者會是哪些人，然后針對他們的特點(diǎn)著重關(guān)注如何才能讓他們理解。

當(dāng)然，文檔也不一定要非常嚴(yán)肅和完美，只要能向你潛在的讀者說明問題即可。記住文檔是寫給別人看的，不是給自己看的。

根據(jù)專業(yè)水平可以大致將讀者分為三種，新手、老手和專家，針對不同水平的人寫作需要有側(cè)重點(diǎn)。

比如針對新手，你需要重點(diǎn)介紹下里面涉及到的術(shù)語和概念，然后詳細(xì)講解具體的的實(shí)現(xiàn)。

相反，針對專家你可以省去這些額外的信息。注意，這里沒有嚴(yán)格的標(biāo)準(zhǔn)，因?yàn)橛行┪恼滦率謺?，專家也會看?這里還是需要具體情況具體分析。

另外一種對讀者分類的方式就是根據(jù)讀者閱讀文檔的目的來分類，比如有人知道自己遇到了什么問題，就是來找解決方案的。

還有一批人只有一個簡單的想法，但不知道具體的問題。舉個例子，以讀數(shù)據(jù)庫慢為例，前者已經(jīng)知道數(shù)據(jù)庫慢可能是因?yàn)閿?shù)據(jù)量巨大且沒有加索引，解決方案很簡單 加索引，這時(shí)候他可能需要知道的是如何正確地加索引。

而后者可能著重關(guān)注的是為什么讀數(shù)據(jù)庫會慢，這時(shí)候你可能需要額外重點(diǎn)介紹下數(shù)據(jù)庫相關(guān)的原理。

③清晰的分類

文檔大致可以分為以下幾種類型，每種類型也有自己不同的特點(diǎn)和寫作側(cè)重點(diǎn)。

參考文檔：也是大部分開發(fā)人員日常會使用和書寫的文檔，比如我們使用某個框架或者工具，都會有 API 說明文檔，這就屬于參考類文檔。

它并沒有太多的要求，只要能向讀者展示清楚如何使用即可，但無需向讀者講明具體的實(shí)現(xiàn)。

注：參考文檔并不僅限于 API 文檔，還包括文件注釋、類注釋、方法注釋，要求都是能準(zhǔn)確說明其用法。

設(shè)計(jì)文檔：很多公司或者團(tuán)隊(duì)在項(xiàng)目開始前都要求有設(shè)計(jì)文檔，設(shè)計(jì)是項(xiàng)目實(shí)施的第一步，所以在設(shè)計(jì)文檔書寫的過程中要求盡可能考慮周全，例如該項(xiàng)目的存儲、交互、隱私……

好的設(shè)計(jì)文檔應(yīng)該包含以下幾個部分：

• 設(shè)計(jì)目標(biāo)
• 實(shí)現(xiàn)的策略
• 各種利弊權(quán)衡和具體決策
• 替代方案
• 各種方案的優(yōu)缺點(diǎn)

寫設(shè)計(jì)文檔的過程也你對整個項(xiàng)目做規(guī)劃、思考可能出現(xiàn)問題的過程，設(shè)計(jì)的越詳細(xì)、思考的越多，未來遇到問題的可能性就會越小。

引導(dǎo)類文檔：也很常見，一般都是 Step by Step 的形式。比如我們在使用某個框架或者工具的時(shí)候，一般都會有個引導(dǎo)類的文檔一步一步幫助你快速上手。大家寫引導(dǎo)類文章大家非常容易犯的一個錯誤就是預(yù)設(shè)了很多背景知識。

一般使用文檔都是有開發(fā)者寫的，他們都非常了解這個工具的相關(guān)的知識，所以習(xí)慣性的會認(rèn)為，啊，這個知識點(diǎn)很簡單，用戶也肯定會吧，實(shí)際上用戶不一定會。

這本質(zhì)上就是一種認(rèn)知偏差，這種現(xiàn)象在跨團(tuán)隊(duì)協(xié)作 尤其是多端協(xié)作的時(shí)候也非常明顯。

這類型的文檔寫作中，要求寫作者盡可能站在用戶的視角上思考，極力避免出現(xiàn)和用戶的認(rèn)知偏差，力爭每個步驟做到明確無歧義，每兩個步驟之間做到緊密銜接。

概念性文檔：當(dāng)參考文檔無法解釋清楚某些東西的時(shí)候，就需要概念性文檔了，比如某個 API 的具體實(shí)現(xiàn)原理。其主要是為了擴(kuò)充參考文檔，而不是替代參考文檔。

有時(shí)候這和參考文檔會有些內(nèi)容重復(fù)，但主要還是為了更深層次的說明某些問題、解釋清楚某個概念。

概念性文檔也是所有文檔中寫作最難的，也是被閱讀最少的，所以很多情況下工程師最容易忽視。

而且還有另外一個問題，沒合適的地方放，參考文檔可以寫代碼里，落地頁可以寫項(xiàng)目主頁里，概念性文檔似乎也只能在項(xiàng)目文檔里找個不起眼的角落存放了。

這類文檔的受眾會比較廣，專家和新手都會去看。另外，它需要強(qiáng)調(diào)概念清晰明了，因此可能會犧牲完整性(可以由參考文檔補(bǔ)齊)，也有可能會犧牲準(zhǔn)確性，這不是說一定要犧牲準(zhǔn)確性，只是應(yīng)當(dāng)分清主次，不重要的就沒必要說了。

Landing pages(落地頁)：就先簡單翻譯成落地頁了，沒想到啥恰當(dāng)?shù)姆g詞。比如一個團(tuán)隊(duì)或者項(xiàng)目的導(dǎo)航頁，雖然沒啥具體的內(nèi)容，但應(yīng)該包含其他頁面的鏈接。

比如你新入職一個團(tuán)隊(duì)，比較成熟的團(tuán)隊(duì)都會扔給你一個文檔，這個文檔里包含常用的工具、文檔鏈接，這就是這個團(tuán)隊(duì)的落地頁。

落地頁的問題就是隨著時(shí)間的推移，頁面可能會變的越來越亂，而且有些內(nèi)容會失效，不過這些問題都好解決，做好定期的維護(hù)和整理就行。

落地頁的技術(shù)難度不高，但要求內(nèi)容的有效性、完整性和分類清晰。

④文檔 Review

在一個組織內(nèi)，光靠個人去維護(hù)文檔是不行的，必須得借助群體的智慧。在一個組織內(nèi)部，文檔的變更也應(yīng)該像代碼的變更一樣，需要被其他人 Review，以提前發(fā)現(xiàn)其中的問題并提升文檔的質(zhì)量。

如何 Review 文檔：

• 專業(yè)的視角來保證準(zhǔn)確性：一般由團(tuán)隊(duì)里比較資深的人負(fù)責(zé)，他們關(guān)注的核心點(diǎn)是文檔寫的對不對，專不專業(yè)。如果 Code Review 做的好的話，文檔的 Review 也屬于 Code Review 的一部分。
• 讀者視角保證簡潔性：一般由不熟悉這個領(lǐng)域的人來 Review，比如團(tuán)隊(duì)的新人，或者文檔的使用者。這部分主要是關(guān)注文檔是否容易被看懂。
• 寫作者視角保證一致性：由寫作經(jīng)驗(yàn)豐富或者相關(guān)領(lǐng)域比較資深的人承擔(dān)，主要是為了保證文檔前后是否一致，比如對同一個專業(yè)術(shù)語的使用和理解是否有歧義。

4、寫文檔的哲學(xué)

上面部分站在組織和團(tuán)隊(duì)的視角來看如何提高文檔質(zhì)量，我們接下來看看站在個人寫作者的視角上如何寫出高質(zhì)量的文檔。

①5W 法則

5W 法則相信大家已經(jīng)聽的多了，分別是 Who、What、When、Where、Why。

這是一個廣泛被用在各行各業(yè)的法則，寫文檔當(dāng)然也能用(5W 法則堪稱萬金油，啥地方都能用)：

• WHO：前面已經(jīng)說過了，文檔是寫給誰看的，讀者是誰。
• WHAT：明確這篇文檔的用途，有時(shí)候，僅僅說明文檔的用途和目的就能幫你搭建起整個文檔的框架。
• WHEN：明確文檔的創(chuàng)建、Review 和更新日期。因?yàn)槲臋n也有時(shí)效性，明確相關(guān)日期可以避免閱讀者踩坑。
• WHERE：文檔應(yīng)該放在哪!建議一個組織或者團(tuán)隊(duì)有統(tǒng)一的永久文檔存放地址，并且有版本控制。最好是方便查找、使用和分享。
• WHY：為什么要寫這篇文檔， 你期望讀者讀完后從文檔中獲得什么!

②三段式寫作

寫文章一般都會有三個部分，專業(yè)寫作者也講究鳳頭、豬肚、豹尾，這三個詞概括出了好文章三部分應(yīng)有的特點(diǎn)。

技術(shù)文檔也算是文章的一種，所以一般也都會有這三部分，每個部分有其自己的作用，比如第一部分闡述問題，中間部分介紹具體的解決方案，第三部分總結(jié)要點(diǎn)。

但這也并不以為著文檔應(yīng)該有三個部分，如果文檔內(nèi)容比較多，可以將其做更細(xì)致的拆解，可以適當(dāng)增加一些冗余的信息幫助讀者理解文檔內(nèi)容。

雖然很多工程師都討厭冗余 極力追求簡潔，但寫文檔和寫代碼不同，適當(dāng)?shù)娜哂喾炊梢詭椭x者理解，很簡單。

舉個例子，比如寫作中經(jīng)常舉例子，舉的例子本質(zhì)上就是冗余信息，生動的例子肯定是能幫助讀者理解抽象內(nèi)容的(我想這就是自舉吧)。

5、結(jié)語

目前看到比較好的一個現(xiàn)象就是大家越來越重視文檔了，但和測試相比 重視的程度還不夠。

測試已經(jīng)是工作流程中不可或缺的一部分了，而文檔依舊還不是。當(dāng)然這可能和文檔本身的特性相關(guān)，測試很容易被自動化，也有非常多的客觀指標(biāo)來評估。

文檔卻做不到，首先文檔的書寫需要人手動介入，而文檔的質(zhì)量也沒有太多客觀的指標(biāo)評估，提升文檔的數(shù)量和質(zhì)量只能從文化和工作流程上去逐漸改變。

最后總結(jié)下本文幾個關(guān)鍵點(diǎn)：

• 隨著時(shí)間的推移和組織規(guī)模的壯大，文檔會越來越重要。
• 文檔也應(yīng)該是開發(fā)流程的一部分。
• 一篇文檔只專注在一件事上。
• 文檔是寫給讀者看的，而不是給你自己看的。

該書電子版近日已經(jīng)可以免費(fèi)下載了，有興趣的同學(xué)可以下載翻閱下：

https://abseil.io/resources/swe_at_google.2.pdf 

作者：xindoo

編輯：陶家龍

出處：cnblogs.com/xindoo/p/15085988.html