如何為你的開源項目編寫實用的文檔
一份優(yōu)質(zhì)的文檔可以讓很多用戶對你的項目路人轉(zhuǎn)粉。
好的代碼很多時候并不代表一切。或許你能用最精巧的代碼解決了世界上最迫切需要解決的問題，但如果你作為一個開源開發(fā)者，沒能用準確的語言將你的作品公之于世，你的代碼也只能成為滄海遺珠。因此，技術(shù)寫作和文檔編寫是很重要的技能。
一般來說，項目中的文檔是最受人關(guān)注的部分，很多用戶會通過文檔來決定自己是否應(yīng)該對某個項目開始學(xué)習(xí)或研究。所以，我們不能忽視技術(shù)寫作和文檔編寫的工作，尤其要重點關(guān)注其中的“入門”部分，這會對你項目的發(fā)展起到關(guān)鍵性的作用。
對于很多人來說，寫作是一件令人厭煩甚至恐懼的事情。我們這些工程師出身的人，更多學(xué)習(xí)的是“寫代碼”而不是學(xué)習(xí)“為代碼寫文檔”。不少人會把英語作為自己的第二語言或者第三語言，他們可能會對英語寫作感到不自信甚至害怕（我的母語是漢語，英語是作為我的第二語言學(xué)習(xí)的，所以我也能感受到這種痛苦）。
但如果你希望自己的項目能在全球范圍內(nèi)產(chǎn)生一定的影響力，英語就是你必須使用的語言，這是一個無法避免的現(xiàn)實。但不必害怕，我在寫這篇文章的時候就考慮到了這些可能帶來的挑戰(zhàn)，并給出了我的一些建議。
五條有用的寫作建議
這五條建議你馬上就可以用起來，盡管看起來似乎有些淺顯，但在技術(shù)寫作時卻經(jīng)常被忽視。
- 使用主動語態(tài)：感受一下主動語態(tài)下的“你可以這樣更改配置（You can change these configurations by…）”和被動語態(tài)下的“配置可以這樣更改（These configurations can be changed by…）”有什么不同之處。
- 使用簡潔明了的句子：可以借助 Hemingway App 或者 Grammarly 這樣的工具，盡管它們并不開源。
- 保持條理性：你可以在文檔中通過寫標題、劃重點、引鏈接等方式，把各類信息劃分為不同的部分，避免將所有內(nèi)容都雜糅在一大段冗長的文字當(dāng)中。
- 提高可讀性：除了單純的文字之外，運用圖表也是從多種角度表達的手段之一。
- 注意拼寫和語法：必須記得檢查文檔中是否有拼寫錯誤或者語法錯誤。
只要在文檔的寫作和編輯過程中應(yīng)用到這些技巧，你就能夠和讀者建立起溝通和信任。
- 高效溝通：對于工程師們來說，閱讀長篇大論的冗長文字，還不如去看小說。在閱讀技術(shù)文檔時，他們總是希望能夠從中快速準確地獲取到有用的信息。因此，技術(shù)文檔的最佳風(fēng)格應(yīng)該是精簡而有效的，不過這并不代表文檔中不能出現(xiàn)類似幽默、emoji 甚至段子這些東西，這些元素可以當(dāng)你的文檔更有個性、更使人印象深刻。當(dāng)然，具體的實現(xiàn)方式就因人而異了
- 建立信任：你需要取得文檔讀者們的信任，這在一個項目的前期尤為重要。讀者對你的信任除了來源于你代碼的質(zhì)量，還跟你文檔編寫的質(zhì)量有關(guān)。所以你不僅要打磨代碼，還要潤色好相關(guān)的文檔，這也是上面第 5 點建議拼寫和語法檢查的原因。
從編寫“入門”文檔開始
現(xiàn)在，最需要花費功夫的應(yīng)該就是“入門”部分了，這是一篇技術(shù)文檔最重要的部分，二八定律在這里得到了充分體現(xiàn)：訪問一個項目的大部分流量都會落在項目文檔上，而訪問項目文檔的大部分流量則會落在文檔的“入門”部分中。因此，如果文檔的“入門”部分寫得足夠好，項目就會吸引到很多用戶，反之，用戶會對你的項目敬而遠之。
那么如何寫好“入門”部分呢？我建議按照以下三步走：
- 任務(wù)化：入門指南應(yīng)該以任務(wù)為導(dǎo)向。這里的任務(wù)指的是對于開發(fā)者來說可以完成的離散的小項目，而不應(yīng)該包含太多涉及到體系結(jié)構(gòu)、核心概念等的抽象信息，因此在“入門”部分只需要提供一個簡單明了的概述就可以了。也不要在“入門”部分大談這個項目如何優(yōu)秀地解決了問題，這個話題可以放在文檔中別的部分進行說明?？偠灾?，“入門”部分最好是給出一些主要的操作步驟，這樣顯得開門見山。
- 30 分鐘內(nèi)能夠完成：這一點的核心是耗時盡可能短，不宜超過 30 分鐘，這個時間上限是考慮到用戶可能對你的項目并不了解。這一點很重要，大部分愿意瀏覽文檔的人都是有技術(shù)基礎(chǔ)的，但對你的項目也僅僅是一知半解。首先讓這些讀者嘗試進行一些相關(guān)操作，在收到一定效果后，他們才會愿意花更多時間深入研究整個項目。因此，你可以從耗時這個角度來評估你的文檔“入門”部分有沒有需要改進之處。
- 有意義的任務(wù)：這里“有意義”的含義取決于你的開源項目。最重要的是認真思考并將“入門”部分嚴格定義為一項任務(wù)，然后交給你的讀者去完成。這個項目的價值應(yīng)該在這項有意義的任務(wù)中有所體現(xiàn)，不然讀者可能會感覺這是一個浪費時間的行為。
提示：假如你的項目是一個分布式數(shù)據(jù)庫，那么達到“整個集群在某些節(jié)點故障的情況下可以不中斷地保持可用”的目標就可以認為是“有意義”的；假如你的項目是一個數(shù)據(jù)分析工具或者是商業(yè)智能工具，“有意義”的目標也可以是“加載數(shù)據(jù)后能快速生成多種可視化效果的儀表板”。總之，無論你的項目需要達到什么“有意義”的目標，都應(yīng)該能在筆記本電腦上本地快速實現(xiàn)。
Linkerd 入門就是一個很好的例子。Linkerd 是一個開源的 Kubernetes 服務(wù)網(wǎng)格，當(dāng)時我對 Kubernetes 了解并不多，也不熟悉服務(wù)網(wǎng)格。但我在自己的筆記本電腦上很輕松地就完成了其中的任務(wù)，同時也加深了對服務(wù)網(wǎng)格的理解。
上面提到的三步過程是一個很有用的框架，對一篇文檔“入門”部分的設(shè)計和量化評估很有幫助。今后你如果想將你的開源項目產(chǎn)品化，這個框架還可能對實現(xiàn)價值的時間產(chǎn)生影響。
其它核心部分
認真寫好“入門”部分之后，你的文檔中還需要有這五個部分：架構(gòu)設(shè)計、生產(chǎn)環(huán)境使用指導(dǎo)、使用案例、參考資料以及未來展望，這五個部分在一份完整的文檔中是必不可少的。
- 架構(gòu)設(shè)計：這一部分需要深入探討整個項目架構(gòu)設(shè)計的依據(jù)，“入門”部分中那些一筆帶過的關(guān)鍵細節(jié)就應(yīng)該在這里體現(xiàn)。在產(chǎn)品化過程中，這個部分將會是產(chǎn)品推廣計劃的核心，因此通常會包含一些可視化呈現(xiàn)的內(nèi)容，期望的效果是讓更多用戶長期參與到項目中來。
- 生產(chǎn)環(huán)境使用指導(dǎo)：對于同一個項目，在生產(chǎn)環(huán)境中部署比在筆記本電腦上部署要復(fù)雜得多。因此，指導(dǎo)用戶認真使用就尤為重要。同時，有些用戶可能對項目很感興趣，但對生產(chǎn)環(huán)境下的使用有所顧慮，而指導(dǎo)和展示的過程則正好能夠吸引到這類潛在的用戶。
- 使用案例：社會認同的力量是有目共睹的，所以很有必要列出正在生產(chǎn)環(huán)境使用這個項目的其他用戶，并把這些信息擺放在顯眼的位置。這個部分的瀏覽量甚至僅次于“入門”部分。
- 參考資料：這個部分是對項目的一些詳細說明，讓用戶得以進行詳細的研究以及查閱相關(guān)信息。一些開源作者會在這個部分事無巨細地列出項目中的每一個細節(jié)和邊緣情況，這種做法可以理解，但不推薦在項目初期就在這個部分花費過多的時間。你可以采取更折中的方式，在質(zhì)量和效率之間取得平衡，例如提供一些相關(guān)社區(qū)的鏈接、Stack Overflow 上的標簽或單獨的 FAQ 頁面。
- 未來展望：你需要制定一個簡略的時間表，規(guī)劃這個項目的未來發(fā)展方向，這會讓用戶長期保持興趣。盡管項目在當(dāng)下可能并不完美，但要讓用戶知道你仍然有完善這個項目的計劃。這個部分也能讓整個社區(qū)構(gòu)建一個強大的生態(tài)，因此還要向用戶提供表達他們對未來展望的看法的交流區(qū)。
以上這幾個部分或許還沒有在你的文檔中出現(xiàn)，甚至可能會在后期才能出現(xiàn)，尤其是“使用案例”部分。盡管如此，還是應(yīng)該在文檔中逐漸加入這些部分。如果用戶對“入門”部分已經(jīng)感覺良好，那以上這幾個部分將會提起用戶更大的興趣。
最后，請在“入門”部分、README 文件或其它顯眼的位置注明整個項目所使用的許可證。這個細節(jié)會讓你的項目更容易通過最終用戶的審核。
花 20% 的時間寫作
一般情況下，我建議把整個項目 10% 到 20% 的時間用在文檔寫作上。也就是說，如果你是全職進行某一個項目的，文檔寫作需要在其中占半天到一天。
再細致一點，應(yīng)該將寫作納入到常規(guī)的工作流程中，這樣它就不再是一件孤立的瑣事，而是日常的事務(wù)。文檔寫作應(yīng)該隨著工作進度同步進行，切忌將所有寫作任務(wù)都堆積起來最后完成，這樣才可以幫助你的項目達到最終目標：吸引用戶、獲得信任。
