在大多數(shù)軟件工程師對(duì)編寫(xiě)、使用和維護(hù)代碼的抱怨中，一個(gè)常見(jiàn)的問(wèn)題是缺乏高質(zhì)量的文檔。缺乏文檔有什么副作用呢？當(dāng)遇到一個(gè)bug時(shí)，這個(gè)縮寫(xiě)是什么意思？這份文件是最新的嗎？在整個(gè)職業(yè)生涯中，每個(gè)軟件工程師都抱怨過(guò)文檔的質(zhì)量、數(shù)量或者完全缺乏文檔。

01

為什么需要寫(xiě)文檔？

高質(zhì)量文檔對(duì)工程組織有巨大的好處。代碼和api變得更容易理解。當(dāng)他們的設(shè)計(jì)目標(biāo)和團(tuán)隊(duì)目標(biāo)被清楚地陳述時(shí)，項(xiàng)目團(tuán)隊(duì)會(huì)更加專(zhuān)注。當(dāng)步驟被清晰地列出時(shí)，手動(dòng)流程更容易遵循。如果過(guò)程被清楚地記錄下來(lái)，那么讓新成員進(jìn)入團(tuán)隊(duì)或代碼庫(kù)所花費(fèi)的精力就會(huì)少得多。但是，由于文檔的好處有一定的滯后性，通常不會(huì)給作者帶來(lái)直接的好處。不像測(cè)試，編寫(xiě)完測(cè)試用例，跑一遍就有結(jié)果。畢竟，你可能只編寫(xiě)了一個(gè)文檔，但之后它將被閱讀數(shù)百次，甚至數(shù)千次；它的初始成本將攤銷(xiāo)給所有未來(lái)的讀者。文檔不僅可以隨著時(shí)間的推移而擴(kuò)展，而且它對(duì)組織的其他部分的擴(kuò)展也很關(guān)鍵。它有助于回答以下的問(wèn)題：

為什么會(huì)做出這些設(shè)計(jì)決策？

為什么要以這種方式實(shí)現(xiàn)這段代碼？

為什么大多數(shù)工程師不喜歡寫(xiě)文檔？

雖然文檔可以帶來(lái)不少好處，為什么工程師通常認(rèn)為它是糟糕的？其中一個(gè)原因，正如我們提到的，是好處不是立竿見(jiàn)影的，特別是對(duì)作者來(lái)說(shuō)。另外還有以下幾點(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ā)工作流程中的話(huà)，寫(xiě)作確實(shí)會(huì)增加工作的負(fù)擔(dān)。

大多數(shù)人將寫(xiě)文檔看做是工作的額外負(fù)擔(dān)。我代碼都沒(méi)時(shí)間寫(xiě)，哪有時(shí)間寫(xiě)文檔！，這其實(shí)是錯(cuò)誤的觀念，文檔雖然前期有投入，但能讓你代碼的后期維護(hù)成本大幅降低，磨刀不誤砍柴工這個(gè)道理相信大家都還是能理解的。

02

寫(xiě)文檔的重要性

另外一個(gè)原因是文檔被視為需要維護(hù)的額外負(fù)擔(dān)，而不是使現(xiàn)有代碼的維護(hù)更容易的東西。寫(xiě)文檔同樣對(duì)作者也有非常大的好處：

它有助于審視API。編寫(xiě)文檔是確定API是否有意義的最可靠的方法之一。通常，編寫(xiě)文檔本身會(huì)使工程師重新評(píng)估設(shè)計(jì)決策。如果你不能解釋它，不能定義它，那你可能還沒(méi)有設(shè)計(jì)好它。

它提供了維護(hù)的歷史記錄。在任何情況下，代碼中的技巧都應(yīng)該避免，但是當(dāng)你盯著兩年前編寫(xiě)的代碼，試圖找出錯(cuò)誤所在時(shí)，好的注釋將提供很大的幫助。

它使你的代碼看起來(lái)更專(zhuān)業(yè)。開(kāi)發(fā)人員自然會(huì)認(rèn)為文檔完備的API就是設(shè)計(jì)得更好的API。雖然情況并非總是如此，但它們通常是高度相關(guān)的。雖然這個(gè)好處聽(tīng)起來(lái)像是表面文章，但事實(shí)并非如此：一個(gè)產(chǎn)品是否有良好的文檔通常是一個(gè)很好的指標(biāo)。

這將減少其他用戶(hù)提出的問(wèn)題。對(duì)于編寫(xiě)文檔的人來(lái)說(shuō)，隨著時(shí)間的推移這可能是最大的好處。如果你必須向某人解釋某件事不止一次，那么記錄該過(guò)程通常是有意義的。

03

像管理代碼一樣管理文檔

軟件工程師使用單一的、主要的編程語(yǔ)言來(lái)編寫(xiě)程序，他們?nèi)匀唤?jīng)常使用不同的語(yǔ)言來(lái)解決特定的問(wèn)題。工程師可能會(huì)編寫(xiě)shell腳本或Python來(lái)運(yùn)行命令行任務(wù)，或者他們可能會(huì)用c++編寫(xiě)大部分后端代碼，但用Java編寫(xiě)一些中間件代碼，等等。每種語(yǔ)言都是工具箱中的一種工具。文檔也應(yīng)該如此：它是一種工具，用不同的語(yǔ)言編寫(xiě)，以完成特定的任務(wù)。編寫(xiě)文檔與編寫(xiě)代碼沒(méi)有多大區(qū)別。與編程語(yǔ)言一樣，它有規(guī)則、特定的語(yǔ)法和樣式?jīng)Q定，通常是為了實(shí)現(xiàn)與代碼中類(lèi)似的目的：加強(qiáng)一致性、提高清晰度和避免理解錯(cuò)誤。文檔通常與代碼緊密耦合，因此應(yīng)該盡可能地將其視為代碼。也就是說(shuō)，文檔也應(yīng)具有如下的屬性：

有明確的責(zé)任人維護(hù)；

有統(tǒng)一的內(nèi)部規(guī)范；

定期更新；

有變更和評(píng)審機(jī)制；

有問(wèn)題反饋和更新機(jī)制；

明確文檔的讀者是誰(shuí)

工程師在編寫(xiě)文檔時(shí)犯的一個(gè)最重要的錯(cuò)誤是只為自己編寫(xiě)文檔。這樣做是很自然的，并且為自己編寫(xiě)代碼并非沒(méi)有價(jià)值：畢竟，你可能需要在幾年后查看這些代碼，并試圖弄清楚你曾經(jīng)的想法?；蛘哒f(shuō)在團(tuán)隊(duì)較小的時(shí)候，大家的工作交集很大，因此也能看懂你的文檔，但是隨著組織的發(fā)展，問(wèn)題就逐漸凸顯，新人會(huì)有這不同背景，團(tuán)隊(duì)大了以后，工作內(nèi)容開(kāi)始細(xì)化，交集減少，這時(shí)候之前寫(xiě)的文檔對(duì)他們來(lái)說(shuō)可能就很難理解了。

因此在開(kāi)始寫(xiě)作之前，應(yīng)該（正式或非正式地）確定文檔需要滿(mǎn)足的受眾。設(shè)計(jì)文件可能需要說(shuō)服決策者。教程可能需要為完全不熟悉代碼庫(kù)的人提供非常明確的說(shuō)明。API可能需要為該API的任何用戶(hù)（無(wú)論是專(zhuān)家還是新手）提供完整和準(zhǔn)確的參考信息。好的文檔不需要修飾或完善。工程師在編寫(xiě)文檔時(shí)所犯的一個(gè)錯(cuò)誤是認(rèn)為他們需要成為更好的作者。按照這個(gè)標(biāo)準(zhǔn)，很少有軟件工程師會(huì)寫(xiě)。記住，我們的觀眾站在你曾經(jīng)站過(guò)的地方，但沒(méi)有你新的領(lǐng)域知識(shí)。所以你不需要成為一個(gè)偉大的作家;你只需要找一個(gè)像你一樣熟悉這個(gè)領(lǐng)域的人。

04

文檔類(lèi)型

作為工作的一部分，工程師會(huì)編寫(xiě)各種不同類(lèi)型的文檔：設(shè)計(jì)文檔、代碼注釋、操作文檔、項(xiàng)目頁(yè)面等等。這些都可以算作文檔。但重要的是要知道不同的類(lèi)型，不要混合類(lèi)型。一般來(lái)說(shuō)，文檔應(yīng)該有一個(gè)單一的目的。正如API應(yīng)該做一件事并且做好一樣，避免在一個(gè)文檔中做幾件事。軟件工程師經(jīng)常需要編寫(xiě)幾種主要類(lèi)型的文檔：

參考文檔，包括注釋

設(shè)計(jì)文檔；

教程；

概念性文檔；

1.參考文檔參考文檔是工程師最常編寫(xiě)的文檔類(lèi)型;事實(shí)上，他們經(jīng)常需要每天寫(xiě)一些參考文檔。代碼注釋是工程師必須維護(hù)的最常見(jiàn)的參考文檔形式。這些注釋可以分為兩個(gè)基本陣營(yíng)：API注釋和實(shí)現(xiàn)注釋。這兩種用戶(hù)之間的區(qū)別：API注釋不需要討論實(shí)現(xiàn)細(xì)節(jié)或設(shè)計(jì)決策，也不要假設(shè)用戶(hù)和作者一樣精通API。但是實(shí)現(xiàn)注釋可以假定讀者有更多的領(lǐng)域知識(shí)，但是要注意不要假設(shè)得太多。

2.設(shè)計(jì)文檔

大多數(shù)公司在項(xiàng)目開(kāi)始之前都需要有設(shè)計(jì)文檔。軟件工程師通常使用團(tuán)隊(duì)批準(zhǔn)的特定設(shè)計(jì)文檔模板來(lái)編寫(xiě)建議的設(shè)計(jì)文檔。然后還需要在特定的團(tuán)隊(duì)會(huì)議上討論或評(píng)論設(shè)計(jì)的細(xì)節(jié)。一個(gè)好的設(shè)計(jì)文檔應(yīng)該涵蓋：

設(shè)計(jì)目標(biāo)

實(shí)現(xiàn)策略

利弊權(quán)衡和具體決策

替代方案

各方案的優(yōu)缺點(diǎn)

一份優(yōu)秀的設(shè)計(jì)文件，一旦獲得批準(zhǔn)，不僅可以作為歷史記錄，還可以作為項(xiàng)目是否成功實(shí)現(xiàn)其目標(biāo)的衡量標(biāo)準(zhǔn)。大多數(shù)團(tuán)隊(duì)會(huì)將他們的設(shè)計(jì)文檔進(jìn)行歸檔，以便在后續(xù)的時(shí)間查看。在產(chǎn)品發(fā)布前檢查設(shè)計(jì)文檔通常是很有用的，以確保編寫(xiě)設(shè)計(jì)文檔時(shí)所陳述的目標(biāo)在發(fā)布時(shí)仍然是所陳述的目標(biāo)（如果不是，那么文件或產(chǎn)品都可以進(jìn)行相應(yīng)的調(diào)整）。

3.教程每個(gè)軟件工程師，當(dāng)他們加入一個(gè)新的團(tuán)隊(duì)時(shí)，都會(huì)想要盡可能快地跟上進(jìn)度。擁有一個(gè)引導(dǎo)人們完成新項(xiàng)目設(shè)置的教程是非常有價(jià)值的。通常情況下，編寫(xiě)教程的最佳時(shí)機(jī)是你第一次加入一個(gè)團(tuán)隊(duì)的時(shí)候。拿個(gè)記事本或其他方法做筆記，寫(xiě)下一路上你需要做的所有事情，假設(shè)沒(méi)有領(lǐng)域知識(shí)或特殊的設(shè)置限制;完成之后，可能會(huì)知道在這個(gè)過(guò)程中所犯的錯(cuò)誤和原因，然后可以編輯你的步驟，以獲得更精簡(jiǎn)的教程。重要的是，寫(xiě)下一路上你需要做的一切;盡量不要假定任何特定的設(shè)置、權(quán)限或領(lǐng)域知識(shí)。這類(lèi)型的文檔寫(xiě)作中，要求寫(xiě)作者盡可能站在用戶(hù)的視角上思考，極力避免出現(xiàn)和用戶(hù)的認(rèn)知偏差，力爭(zhēng)每個(gè)步驟做到明確無(wú)歧義，每?jī)蓚€(gè)步驟之間做到緊密銜接。

4.概念性文檔有些代碼需要更深入的解釋或見(jiàn)解，而不是僅僅通過(guò)閱讀參考文檔就能得到的。在這些情況下，我們需要概念性文檔來(lái)提供api或系統(tǒng)的概述。

概念性文檔處理可能是API的庫(kù)概述、描述服務(wù)器中數(shù)據(jù)生命周期的文檔等。概念性文檔是用來(lái)擴(kuò)充而不是替換參考文檔集的。有時(shí)候這和參考文檔會(huì)有些內(nèi)容重復(fù)，，但主要還是為了更深層次的說(shuō)明某些問(wèn)題、解釋清楚某個(gè)概念。概念性文檔沒(méi)有必要涵蓋所有邊緣情況。在這種情況下，為了清晰度而犧牲一些準(zhǔn)確性是可以接受的。概念性文件的要點(diǎn)在于傳達(dá)理解。概念文檔是最難編寫(xiě)的文檔形式。因此，它們通常是軟件工程師工具箱中最容易被忽視的文檔類(lèi)型。而且還有另外一個(gè)問(wèn)題，沒(méi)合適的地方放，參考文檔可以寫(xiě)代碼里，落地頁(yè)可以寫(xiě)項(xiàng)目主頁(yè)里，概念性文檔似乎也只能在項(xiàng)目文檔里找個(gè)不起眼的角落存放了。概念文檔需要對(duì)廣泛的受眾有用：無(wú)論是專(zhuān)家還是新手。此外，它需要強(qiáng)調(diào)清晰性，所以它通常需要犧牲完整性（最好留作參考）和（有時(shí)）嚴(yán)格的準(zhǔn)確性。這并不是說(shuō)概念性文件應(yīng)該故意不準(zhǔn)確;這只是意味著它應(yīng)該關(guān)注常見(jiàn)的用法，而將罕見(jiàn)的用法或副作用留作參考文檔。

05

文檔Review

在一個(gè)組織內(nèi)，光靠個(gè)人去維護(hù)文檔是不行的，必須得借助群體的智慧。在一個(gè)組織內(nèi)部，文檔的變更也應(yīng)該像代碼的變更一樣，需要被其他人Review，以提前發(fā)現(xiàn)其中的問(wèn)題并提升文檔的質(zhì)量。技術(shù)文檔得益于三種不同類(lèi)型的review，每種審查都強(qiáng)調(diào)不同的方面：

專(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做的好的話(huà)，文檔的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ǔ)的使用和理解是否有歧義。

06

文檔寫(xiě)作的哲學(xué)

下面的部分更多地是關(guān)于技術(shù)寫(xiě)作最佳實(shí)踐的論述。5W法則相信大家已經(jīng)聽(tīng)的多了，分別是WHO， WHAT， WHEN， WHERE， WHY，這是一個(gè)廣泛被用在各行各業(yè)的法則，寫(xiě)文檔當(dāng)然也不例外。WHO：正如前面所說(shuō)，文檔的針對(duì)對(duì)象是誰(shuí)，讀者是誰(shuí)。

WHAT：明確文檔寫(xiě)作的用途，通常僅需說(shuō)明文檔的用途和目的就能幫你搭建起整個(gè)文檔的框架。

WHEN：明確文檔的創(chuàng)建、Review和更新日期。因?yàn)槲臋n也有時(shí)效性，明確相關(guān)日期可以避免閱讀者踩坑。

WHERE：文檔應(yīng)該放在哪！建議一個(gè)組織或者團(tuán)隊(duì)有統(tǒng)一的永久文檔存放地址，并且有版本控制。最好是方便查找、使用和分享。

WHY：為什么要寫(xiě)這篇文檔， 你期望讀者讀完后從文檔中獲得什么！

1.三段式文檔

所有文檔，文檔的所有部分都有開(kāi)頭、中間和結(jié)尾。盡管這聽(tīng)起來(lái)非常愚蠢，但大多數(shù)文件通常都應(yīng)該有這三個(gè)部分。不要害怕在文檔中添加章節(jié);它們將流程分解為邏輯部分，并為讀者提供文檔所涵蓋內(nèi)容的路線(xiàn)圖。

通常開(kāi)頭部分代表問(wèn)題，中間部分介紹推薦的解決方案，結(jié)尾部分總結(jié)結(jié)論。但這也并不以為著文檔應(yīng)該有三個(gè)部分，如果文檔內(nèi)容比較多，可以將其做更細(xì)致的拆解，可以適當(dāng)增加一些冗余的信息幫助讀者理解文檔內(nèi)容。雖然很多工程師都討厭冗余 極力追求簡(jiǎn)潔，但寫(xiě)文檔和寫(xiě)代碼不同，適當(dāng)?shù)娜哂喾炊梢詭椭x者理解。

2.好文檔必備的屬性

好的文檔通常有三個(gè)方面：完整性、準(zhǔn)確性和清晰度。很少在同一個(gè)文檔中同時(shí)獲得這三種信息;例如，當(dāng)你試圖使文檔更完整時(shí)，清晰度就會(huì)開(kāi)始受到影響。如果您試圖記錄API的每個(gè)可能的用例，您可能會(huì)得到一個(gè)難以理解的混亂。對(duì)于編程語(yǔ)言來(lái)說(shuō)，在所有情況下都做到完全準(zhǔn)確（并記錄所有可能的副作用）也會(huì)影響清晰度。對(duì)于其他文件，試圖明確一個(gè)復(fù)雜的主題可能會(huì)微妙地影響文件的準(zhǔn)確性;例如，您可能決定忽略概念性文檔中的一些罕見(jiàn)的副作用，因?yàn)槲臋n的目的是讓人們熟悉API的用法，而不是提供對(duì)所有預(yù)期行為的武斷概述。

在每種情況下，一個(gè)好的文檔都被定義為正在執(zhí)行其預(yù)期工作的文檔。因此，您很少希望文檔執(zhí)行一項(xiàng)以上的工作。對(duì)于每個(gè)文檔（以及每個(gè)文檔類(lèi)型），確定其重點(diǎn)并適當(dāng)調(diào)整編寫(xiě)，寫(xiě)概念性文檔可能不需要涵蓋API的每個(gè)部分，寫(xiě)一個(gè)參考可能想要這個(gè)完整，但可能必須犧牲一些清晰度等。所有這些加起來(lái)就是質(zhì)量，不可否認(rèn)的是，質(zhì)量很難精確衡量。

07

結(jié)論

公平地說(shuō)，對(duì)文檔的處理與對(duì)測(cè)試的處理并不一定相同。對(duì)測(cè)試來(lái)講可以進(jìn)行原子測(cè)試（單元測(cè)試），并遵循規(guī)定的形式和功能。在大多數(shù)情況下，文件不能。測(cè)試可以自動(dòng)化，但通常缺乏自動(dòng)化文檔的方案。文件必然是主觀的;文檔的質(zhì)量不是由作者來(lái)衡量的，而是由讀者來(lái)衡量的，而且通常是異步的。

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

隨著時(shí)間推移，團(tuán)隊(duì)的壯大，文檔會(huì)越來(lái)越重要；

文檔應(yīng)該是開(kāi)發(fā)人員工作流程的一部分；

每篇文檔專(zhuān)注于一個(gè)目的；

文檔是給讀者看的，而不是你自己寫(xiě)作。

責(zé)任編輯：haq