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