如何為你的開源項目編寫實用的文檔

好的代碼很多時候並不代表一切。或許你能用最精巧的代碼解決了世界上最迫切需要解決的問題，但如果你作為一個開源開發者，沒能用準確的語言將你的作品公之於世，你的代碼也只能成為滄海遺珠。因此，技術寫作和文檔編寫是很重要的技能。

一般來說，項目中的文檔是最受人關注的部分，很多用戶會通過文檔來決定自己是否應該對某個項目開始學習或研究。所以，我們不能忽視技術寫作和文檔編寫的工作，尤其要重點關注其中的「 入門 Getting Started 」部分，這會對你項目的發展起到關鍵性的作用。

對於很多人來說，寫作是一件令人厭煩甚至恐懼的事情。我們這些工程師出身的人，更多學習的是「寫代碼」而不是學習「為代碼寫文檔」。不少人會把英語作為自己的第二語言或者第三語言，他們可能會對英語寫作感到不自信甚至害怕（我的母語是漢語，英語是作為我的第二語言學習的，所以我也能感受到這種痛苦）。

但如果你希望自己的項目能在全球範圍內產生一定的影響力，英語就是你必須使用的語言，這是一個無法避免的現實。但不必害怕，我在寫這篇文章的時候就考慮到了這些可能帶來的挑戰，並給出了我的一些建議。

五條有用的寫作建議

這五條建議你馬上就可以用起來，儘管看起來似乎有些淺顯，但在技術寫作時卻經常被忽視。

1. 使用主動語態：感受一下主動語態下的「你可以這樣更改配置（You can change these configurations by…）」和被動語態下的「配置可以這樣更改（These configurations can be changed by…）」有什麼不同之處。
2. 使用簡潔明了的句子：可以藉助 Hemingway App 或者 Grammarly 這樣的工具，儘管它們並不開源。
3. 保持條理性：你可以在文檔中通過寫標題、劃重點、引鏈接等方式，把各類信息劃分為不同的部分，避免將所有內容都雜糅在一大段冗長的文字當中。
4. 提高可讀性：除了單純的文字之外，運用圖表也是從多種角度表達的手段之一。
5. 注意拼寫和語法：必須記得檢查文檔中是否有拼寫錯誤或者語法錯誤。

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

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

從編寫「入門」文檔開始

現在，最需要花費功夫的應該就是「入門」部分了，這是一篇技術文檔最重要的部分，二八定律在這裡得到了充分體現：訪問一個項目的大部分流量都會落在項目文檔上，而訪問項目文檔的大部分流量則會落在文檔的「入門」部分中。因此，如果文檔的「入門」部分寫得足夠好，項目就會吸引到很多用戶，反之，用戶會對你的項目敬而遠之。

那麼如何寫好「入門」部分呢？我建議按照以下三步走：

1. 任務化：入門指南應該以任務為導向。這裡的任務指的是對於開發者來說可以完成的離散的小項目，而不應該包含太多涉及到體系結構、核心概念等的抽象信息，因此在「入門」部分只需要提供一個簡單明了的概述就可以了。也不要在「入門」部分大談這個項目如何優秀地解決了問題，這個話題可以放在文檔中別的部分進行說明。總而言之，「入門」部分最好是給出一些主要的操作步驟，這樣顯得開門見山。
2. 30 分鐘內能夠完成：這一點的核心是耗時儘可能短，不宜超過 30 分鐘，這個時間上限是考慮到用戶可能對你的項目並不了解。這一點很重要，大部分願意瀏覽文檔的人都是有技術基礎的，但對你的項目也僅僅是一知半解。首先讓這些讀者嘗試進行一些相關操作，在收到一定效果後，他們才會願意花更多時間深入研究整個項目。因此，你可以從耗時這個角度來評估你的文檔「入門」部分有沒有需要改進之處。
3. 有意義的任務：這裡「有意義」的含義取決於你的開源項目。最重要的是認真思考並將「入門」部分嚴格定義為一項任務，然後交給你的讀者去完成。這個項目的價值應該在這項有意義的任務中有所體現，不然讀者可能會感覺這是一個浪費時間的行為。

提示：假如你的項目是一個分散式資料庫，那麼達到「整個集群在某些節點故障的情況下可以不中斷地保持可用」的目標就可以認為是「有意義」的；假如你的項目是一個數據分析工具或者是商業智能工具，「有意義」的目標也可以是「載入數據後能快速生成多種可視化效果的儀錶板」。總之，無論你的項目需要達到什麼「有意義」的目標，都應該能在筆記本電腦上本地快速實現。

Linkerd 入門就是一個很好的例子。Linkerd 是一個開源的 Kubernetes 服務網格 Service Mesh ，當時我對 Kubernetes 了解並不多，也不熟悉服務網格。但我在自己的筆記本電腦上很輕鬆地就完成了其中的任務，同時也加深了對服務網格的理解。

上面提到的三步過程是一個很有用的框架，對一篇文檔「入門」部分的設計和量化評估很有幫助。今後你如果想將你的開源項目產品化，這個框架還可能對 實現價值的時間 time-to-value 產生影響。

其它核心部分

認真寫好「入門」部分之後，你的文檔中還需要有這五個部分：架構設計、生產環境使用指導、使用案例、參考資料以及未來展望，這五個部分在一份完整的文檔中是必不可少的。

• 架構設計：這一部分需要深入探討整個項目架構設計的依據，「入門」部分中那些一筆帶過的關鍵細節就應該在這裡體現。在產品化過程中，這個部分將會是產品推廣計劃的核心，因此通常會包含一些可視化呈現的內容，期望的效果是讓更多用戶長期參與到項目中來。
• 生產環境使用指導：對於同一個項目，在生產環境中部署比在筆記本電腦上部署要複雜得多。因此，指導用戶認真使用就尤為重要。同時，有些用戶可能對項目很感興趣，但對生產環境下的使用有所顧慮，而指導和展示的過程則正好能夠吸引到這類潛在的用戶。
• 使用案例： 社會認同 social proof 的力量是有目共睹的，所以很有必要列出正在生產環境使用這個項目的其他用戶，並把這些信息擺放在顯眼的位置。這個部分的瀏覽量甚至僅次於「入門」部分。
• 參考資料：這個部分是對項目的一些詳細說明，讓用戶得以進行詳細的研究以及查閱相關信息。一些開源作者會在這個部分事無巨細地列出項目中的每一個細節和 邊緣情況 edge case ，這種做法可以理解，但不推薦在項目初期就在這個部分花費過多的時間。你可以採取更折中的方式，在質量和效率之間取得平衡，例如提供一些相關社區的鏈接、Stack Overflow 上的標籤或單獨的 FAQ 頁面。
• 未來展望：你需要制定一個簡略的時間表，規劃這個項目的未來發展方向，這會讓用戶長期保持興趣。儘管項目在當下可能並不完美，但要讓用戶知道你仍然有完善這個項目的計劃。這個部分也能讓整個社區構建一個強大的生態，因此還要向用戶提供表達他們對未來展望的看法的交流區。

以上這幾個部分或許還沒有在你的文檔中出現，甚至可能會在後期才能出現，尤其是「使用案例」部分。儘管如此，還是應該在文檔中逐漸加入這些部分。如果用戶對「入門」部分已經感覺良好，那以上這幾個部分將會提起用戶更大的興趣。

最後，請在「入門」部分、README 文件或其它顯眼的位置註明整個項目所使用的許可證。這個細節會讓你的項目更容易通過最終用戶的審核。

花 20% 的時間寫作

一般情況下，我建議把整個項目 10% 到 20% 的時間用在文檔寫作上。也就是說，如果你是全職進行某一個項目的，文檔寫作需要在其中佔半天到一天。

再細緻一點，應該將寫作納入到常規的工作流程中，這樣它就不再是一件孤立的瑣事，而是日常的事務。文檔寫作應該隨著工作進度同步進行，切忌將所有寫作任務都堆積起來最後完成，這樣才可以幫助你的項目達到最終目標：吸引用戶、獲得信任。

特別鳴謝雲原生計算基金會的佈道師 Luc Perkins 給出的寶貴意見。

本文首發於 COSS Media 並經許可發布。

via: https://opensource.com/article/20/3/documentation

作者：Kevin Xu 選題：lujun9972 譯者：HankChow 校對：wxy

本文由 LCTT 原創編譯，Linux中國 榮譽推出

本文轉載來自 Linux 中國: https://github.com/Linux-CN/archive