[[320401]]

一份優(yōu)質(zhì)的文檔可以讓很多用戶(hù)對(duì)你的項(xiàng)目路人轉(zhuǎn)粉。

好的代碼很多時(shí)候并不代表一切?；蛟S你能用最精巧的代碼解決了世界上最迫切需要解決的問(wèn)題，但如果你作為一個(gè)開(kāi)源開(kāi)發(fā)者，沒(méi)能用準(zhǔn)確的語(yǔ)言將你的作品公之于世，你的代碼也只能成為滄海遺珠。因此，技術(shù)寫(xiě)作和文檔編寫(xiě)是很重要的技能。

一般來(lái)說(shuō)，項(xiàng)目中的文檔是最受人關(guān)注的部分，很多用戶(hù)會(huì)通過(guò)文檔來(lái)決定自己是否應(yīng)該對(duì)某個(gè)項(xiàng)目開(kāi)始學(xué)習(xí)或研究。所以，我們不能忽視技術(shù)寫(xiě)作和文檔編寫(xiě)的工作，尤其要重點(diǎn)關(guān)注其中的“入門(mén)Getting Started”部分，這會(huì)對(duì)你項(xiàng)目的發(fā)展起到關(guān)鍵性的作用。

對(duì)于很多人來(lái)說(shuō)，寫(xiě)作是一件令人厭煩甚至恐懼的事情。我們這些工程師出身的人，更多學(xué)習(xí)的是“寫(xiě)代碼”而不是學(xué)習(xí)“為代碼寫(xiě)文檔”。不少人會(huì)把英語(yǔ)作為自己的第二語(yǔ)言或者第三語(yǔ)言，他們可能會(huì)對(duì)英語(yǔ)寫(xiě)作感到不自信甚至害怕（我的母語(yǔ)是漢語(yǔ)，英語(yǔ)是作為我的第二語(yǔ)言學(xué)習(xí)的，所以我也能感受到這種痛苦）。

但如果你希望自己的項(xiàng)目能在全球范圍內(nèi)產(chǎn)生一定的影響力，英語(yǔ)就是你必須使用的語(yǔ)言，這是一個(gè)無(wú)法避免的現(xiàn)實(shí)。但不必害怕，我在寫(xiě)這篇文章的時(shí)候就考慮到了這些可能帶來(lái)的挑戰(zhàn)，并給出了我的一些建議。

五條有用的寫(xiě)作建議

這五條建議你馬上就可以用起來(lái)，盡管看起來(lái)似乎有些淺顯，但在技術(shù)寫(xiě)作時(shí)卻經(jīng)常被忽視。

1. 使用主動(dòng)語(yǔ)態(tài)：感受一下主動(dòng)語(yǔ)態(tài)下的“你可以這樣更改配置（You can change these configurations by…）”和被動(dòng)語(yǔ)態(tài)下的“配置可以這樣更改（These configurations can be changed by…）”有什么不同之處。
2. 使用簡(jiǎn)潔明了的句子：可以借助 Hemingway App 或者 Grammarly 這樣的工具，盡管它們并不開(kāi)源。
3. 保持條理性：你可以在文檔中通過(guò)寫(xiě)標(biāo)題、劃重點(diǎn)、引鏈接等方式，把各類(lèi)信息劃分為不同的部分，避免將所有內(nèi)容都雜糅在一大段冗長(zhǎng)的文字當(dāng)中。
4. 提高可讀性：除了單純的文字之外，運(yùn)用圖表也是從多種角度表達(dá)的手段之一。
5. 注意拼寫(xiě)和語(yǔ)法：必須記得檢查文檔中是否有拼寫(xiě)錯(cuò)誤或者語(yǔ)法錯(cuò)誤。

只要在文檔的寫(xiě)作和編輯過(guò)程中應(yīng)用到這些技巧，你就能夠和讀者建立起溝通和信任。

• 高效溝通：對(duì)于工程師們來(lái)說(shuō)，閱讀長(zhǎng)篇大論的冗長(zhǎng)文字，還不如去看小說(shuō)。在閱讀技術(shù)文檔時(shí)，他們總是希望能夠從中快速準(zhǔn)確地獲取到有用的信息。因此，技術(shù)文檔的最佳風(fēng)格應(yīng)該是精簡(jiǎn)而有效的，不過(guò)這并不代表文檔中不能出現(xiàn)類(lèi)似幽默、emoji 甚至段子這些東西，這些元素可以當(dāng)你的文檔更有個(gè)性、更使人印象深刻。當(dāng)然，具體的實(shí)現(xiàn)方式就因人而異了
• 建立信任：你需要取得文檔讀者們的信任，這在一個(gè)項(xiàng)目的前期尤為重要。讀者對(duì)你的信任除了來(lái)源于你代碼的質(zhì)量，還跟你文檔編寫(xiě)的質(zhì)量有關(guān)。所以你不僅要打磨代碼，還要潤(rùn)色好相關(guān)的文檔，這也是上面第 5 點(diǎn)建議拼寫(xiě)和語(yǔ)法檢查的原因。

從編寫(xiě)“入門(mén)”文檔開(kāi)始

現(xiàn)在，最需要花費(fèi)功夫的應(yīng)該就是“入門(mén)”部分了，這是一篇技術(shù)文檔最重要的部分，二八定律在這里得到了充分體現(xiàn)：訪(fǎng)問(wèn)一個(gè)項(xiàng)目的大部分流量都會(huì)落在項(xiàng)目文檔上，而訪(fǎng)問(wèn)項(xiàng)目文檔的大部分流量則會(huì)落在文檔的“入門(mén)”部分中。因此，如果文檔的“入門(mén)”部分寫(xiě)得足夠好，項(xiàng)目就會(huì)吸引到很多用戶(hù)，反之，用戶(hù)會(huì)對(duì)你的項(xiàng)目敬而遠(yuǎn)之。

那么如何寫(xiě)好“入門(mén)”部分呢？我建議按照以下三步走：

1. 任務(wù)化：入門(mén)指南應(yīng)該以任務(wù)為導(dǎo)向。這里的任務(wù)指的是對(duì)于開(kāi)發(fā)者來(lái)說(shuō)可以完成的離散的小項(xiàng)目，而不應(yīng)該包含太多涉及到體系結(jié)構(gòu)、核心概念等的抽象信息，因此在“入門(mén)”部分只需要提供一個(gè)簡(jiǎn)單明了的概述就可以了。也不要在“入門(mén)”部分大談這個(gè)項(xiàng)目如何優(yōu)秀地解決了問(wèn)題，這個(gè)話(huà)題可以放在文檔中別的部分進(jìn)行說(shuō)明?？偠灾?，“入門(mén)”部分最好是給出一些主要的操作步驟，這樣顯得開(kāi)門(mén)見(jiàn)山。
2. 30 分鐘內(nèi)能夠完成：這一點(diǎn)的核心是耗時(shí)盡可能短，不宜超過(guò) 30 分鐘，這個(gè)時(shí)間上限是考慮到用戶(hù)可能對(duì)你的項(xiàng)目并不了解。這一點(diǎn)很重要，大部分愿意瀏覽文檔的人都是有技術(shù)基礎(chǔ)的，但對(duì)你的項(xiàng)目也僅僅是一知半解。首先讓這些讀者嘗試進(jìn)行一些相關(guān)操作，在收到一定效果后，他們才會(huì)愿意花更多時(shí)間深入研究整個(gè)項(xiàng)目。因此，你可以從耗時(shí)這個(gè)角度來(lái)評(píng)估你的文檔“入門(mén)”部分有沒(méi)有需要改進(jìn)之處。
3. 有意義的任務(wù)：這里“有意義”的含義取決于你的開(kāi)源項(xiàng)目。最重要的是認(rèn)真思考并將“入門(mén)”部分嚴(yán)格定義為一項(xiàng)任務(wù)，然后交給你的讀者去完成。這個(gè)項(xiàng)目的價(jià)值應(yīng)該在這項(xiàng)有意義的任務(wù)中有所體現(xiàn)，不然讀者可能會(huì)感覺(jué)這是一個(gè)浪費(fèi)時(shí)間的行為。

提示：假如你的項(xiàng)目是一個(gè)分布式數(shù)據(jù)庫(kù)，那么達(dá)到“整個(gè)集群在某些節(jié)點(diǎn)故障的情況下可以不中斷地保持可用”的目標(biāo)就可以認(rèn)為是“有意義”的；假如你的項(xiàng)目是一個(gè)數(shù)據(jù)分析工具或者是商業(yè)智能工具，“有意義”的目標(biāo)也可以是“加載數(shù)據(jù)后能快速生成多種可視化效果的儀表板”?？傊?，無(wú)論你的項(xiàng)目需要達(dá)到什么“有意義”的目標(biāo)，都應(yīng)該能在筆記本電腦上本地快速實(shí)現(xiàn)。

Linkerd 入門(mén)就是一個(gè)很好的例子。Linkerd 是一個(gè)開(kāi)源的 Kubernetes 服務(wù)網(wǎng)格Service Mesh，當(dāng)時(shí)我對(duì) Kubernetes 了解并不多，也不熟悉服務(wù)網(wǎng)格。但我在自己的筆記本電腦上很輕松地就完成了其中的任務(wù)，同時(shí)也加深了對(duì)服務(wù)網(wǎng)格的理解。

上面提到的三步過(guò)程是一個(gè)很有用的框架，對(duì)一篇文檔“入門(mén)”部分的設(shè)計(jì)和量化評(píng)估很有幫助。今后你如果想將你的開(kāi)源項(xiàng)目產(chǎn)品化，這個(gè)框架還可能對(duì)實(shí)現(xiàn)價(jià)值的時(shí)間time-to-value產(chǎn)生影響。

其它核心部分

認(rèn)真寫(xiě)好“入門(mén)”部分之后，你的文檔中還需要有這五個(gè)部分：架構(gòu)設(shè)計(jì)、生產(chǎn)環(huán)境使用指導(dǎo)、使用案例、參考資料以及未來(lái)展望，這五個(gè)部分在一份完整的文檔中是必不可少的。

• 架構(gòu)設(shè)計(jì)：這一部分需要深入探討整個(gè)項(xiàng)目架構(gòu)設(shè)計(jì)的依據(jù)，“入門(mén)”部分中那些一筆帶過(guò)的關(guān)鍵細(xì)節(jié)就應(yīng)該在這里體現(xiàn)。在產(chǎn)品化過(guò)程中，這個(gè)部分將會(huì)是產(chǎn)品推廣計(jì)劃的核心，因此通常會(huì)包含一些可視化呈現(xiàn)的內(nèi)容，期望的效果是讓更多用戶(hù)長(zhǎng)期參與到項(xiàng)目中來(lái)。
• 生產(chǎn)環(huán)境使用指導(dǎo)：對(duì)于同一個(gè)項(xiàng)目，在生產(chǎn)環(huán)境中部署比在筆記本電腦上部署要復(fù)雜得多。因此，指導(dǎo)用戶(hù)認(rèn)真使用就尤為重要。同時(shí)，有些用戶(hù)可能對(duì)項(xiàng)目很感興趣，但對(duì)生產(chǎn)環(huán)境下的使用有所顧慮，而指導(dǎo)和展示的過(guò)程則正好能夠吸引到這類(lèi)潛在的用戶(hù)。
• 使用案例：社會(huì)認(rèn)同social proof的力量是有目共睹的，所以很有必要列出正在生產(chǎn)環(huán)境使用這個(gè)項(xiàng)目的其他用戶(hù)，并把這些信息擺放在顯眼的位置。這個(gè)部分的瀏覽量甚至僅次于“入門(mén)”部分。
• 參考資料：這個(gè)部分是對(duì)項(xiàng)目的一些詳細(xì)說(shuō)明，讓用戶(hù)得以進(jìn)行詳細(xì)的研究以及查閱相關(guān)信息。一些開(kāi)源作者會(huì)在這個(gè)部分事無(wú)巨細(xì)地列出項(xiàng)目中的每一個(gè)細(xì)節(jié)和邊緣情況edge case，這種做法可以理解，但不推薦在項(xiàng)目初期就在這個(gè)部分花費(fèi)過(guò)多的時(shí)間。你可以采取更折中的方式，在質(zhì)量和效率之間取得平衡，例如提供一些相關(guān)社區(qū)的鏈接、Stack Overflow 上的標(biāo)簽或單獨(dú)的 FAQ 頁(yè)面。
• 未來(lái)展望：你需要制定一個(gè)簡(jiǎn)略的時(shí)間表，規(guī)劃這個(gè)項(xiàng)目的未來(lái)發(fā)展方向，這會(huì)讓用戶(hù)長(zhǎng)期保持興趣。盡管項(xiàng)目在當(dāng)下可能并不完美，但要讓用戶(hù)知道你仍然有完善這個(gè)項(xiàng)目的計(jì)劃。這個(gè)部分也能讓整個(gè)社區(qū)構(gòu)建一個(gè)強(qiáng)大的生態(tài)，因此還要向用戶(hù)提供表達(dá)他們對(duì)未來(lái)展望的看法的交流區(qū)。

以上這幾個(gè)部分或許還沒(méi)有在你的文檔中出現(xiàn)，甚至可能會(huì)在后期才能出現(xiàn)，尤其是“使用案例”部分。盡管如此，還是應(yīng)該在文檔中逐漸加入這些部分。如果用戶(hù)對(duì)“入門(mén)”部分已經(jīng)感覺(jué)良好，那以上這幾個(gè)部分將會(huì)提起用戶(hù)更大的興趣。

最后，請(qǐng)?jiān)?ldquo;入門(mén)”部分、README 文件或其它顯眼的位置注明整個(gè)項(xiàng)目所使用的許可證。這個(gè)細(xì)節(jié)會(huì)讓你的項(xiàng)目更容易通過(guò)最終用戶(hù)的審核。

花 20% 的時(shí)間寫(xiě)作

一般情況下，我建議把整個(gè)項(xiàng)目 10% 到 20% 的時(shí)間用在文檔寫(xiě)作上。也就是說(shuō)，如果你是全職進(jìn)行某一個(gè)項(xiàng)目的，文檔寫(xiě)作需要在其中占半天到一天。

再細(xì)致一點(diǎn)，應(yīng)該將寫(xiě)作納入到常規(guī)的工作流程中，這樣它就不再是一件孤立的瑣事，而是日常的事務(wù)。文檔寫(xiě)作應(yīng)該隨著工作進(jìn)度同步進(jìn)行，切忌將所有寫(xiě)作任務(wù)都堆積起來(lái)最后完成，這樣才可以幫助你的項(xiàng)目達(dá)到最終目標(biāo)：吸引用戶(hù)、獲得信任。