本文發表於一年多前。舊文章可能包含過時內容。請檢查頁面中的資訊自發布以來是否已變得不正確。

探索文件

作者：Aimee Ukasick（獨立貢獻者） |
grok: to understand profoundly and intuitively

定義由 Merriam Webster 線上詞典提供

引言 - 新 SIG Docs 貢獻者的觀察

我於 2019 年 8 月開始為 SIG Docs 社群貢獻。有時我感覺自己像一個異鄉人，在一個陌生的地方適應一個新的社群：調查社群組織、理解貢獻者社會、學習新知識並融入新術語。我既是觀察者，也是貢獻者。

觀察 01：閱讀《貢獻》頁面！

我曾為 OpenStack、OPNFV 和 Acumos 貢獻過程式碼和文件，所以我認為為 Kubernetes 文件做貢獻也會是一樣的。我錯了。我應該仔細**閱讀**貢獻 Kubernetes 文件頁面，而不是粗略瀏覽。

我對 git/gerrit 工作流程非常熟悉。使用這些工具，貢獻者克隆 `master` 倉庫，然後建立一個本地分支。Kubernetes 使用一種不同的方法，稱為“Fork and Pull”（派生並拉取）。每個貢獻者 `fork` master 倉庫，然後將工作推送到自己的派生倉庫，再建立拉取請求。我按照“開始貢獻”頁面中提交拉取請求部分的說明，建立了一個簡單的拉取請求（PR）。該部分描述瞭如何使用 GitHub UI 進行文件更改。我瞭解到，這種方法對於只需要一次提交即可修復的更改是可行的。但是，當您必須對 PR 進行額外更新時，此方法會變得複雜。每次使用 GitHub UI 進行更改時，GitHub 都會建立一個新的提交。Kubernetes GitHub 組織要求壓縮提交。 “開始貢獻”頁面沒有提及壓縮提交，所以我查看了 GitHub 和 git 文件。我無法使用 GitHub UI 壓縮我的提交。我必須在本地 `git fetch` 和 `git checkout` 我的拉取請求，使用命令列壓縮提交，然後推送我的更改。如果“開始貢獻”提及了壓縮提交，我就會從本地克隆開始工作，而不是使用 GitHub UI。

觀察 02：主動聯絡某人

在處理我的第一個 PR 時，我對從本地克隆工作以及如何使我的派生與 `upstream master` 保持同步有疑問。我選擇在網際網路上搜索，而不是在 Kubernetes Slack #sig-docs 頻道提問。我使用了錯誤的流程來更新我的派生，所以我不得不 `git rebase` 我的 PR，結果非常糟糕。因此，我關閉了這些 PR 並提交了新的。當我在 #sig-docs 頻道尋求幫助時，貢獻者們釋出了有用的連結，我的本地 git 配置檔案應該是什麼樣子，以及要執行的準確的 git 命令集。貢獻者使用的流程與“中級貢獻”頁面中定義的流程不同。如果我早點詢問應該使用哪種 GitHub 工作流程，我本可以節省大量時間。社群知識記錄得越多，新貢獻者就越容易快速提高生產力。

觀察 03：不要讓衝突資訊毀了你的一天

Kubernetes 社群有關於程式碼的貢獻者指南，以及關於文件的另一個指南。這些指南在同一主題上包含衝突資訊。例如，SIG Docs GitHub 流程建議基於 `upstream/master` 建立本地分支。Kubernetes 社群貢獻者指南則倡導從上游更新你的 fork，然後基於你的 fork 建立本地分支。新貢獻者應該遵循哪個流程？這兩個流程是否可以互換？提出有關衝突資訊問題的最佳地點是 #sig-docs 或 #sig-contribex 頻道。我在 #sig-contribex 頻道詢問了有關 GitHub 工作流的澄清問題。@cblecker 提供了一個非常詳細的回覆，我用它來更新了**中間貢獻**頁面。

觀察 04：資訊可能分散

對於大型開源專案來說，資訊分散在各個倉庫或在倉庫之間重複是很常見的。有時團隊各自為政，資訊不共享。有時，一個人離開了去從事不同的專案，而沒有傳承專業知識。文件空白存在，並且由於優先順序較高的事項可能永遠無法糾正。因此，新貢獻者可能難以找到基本資訊，例如會議詳情。

參加 SIG Docs 會議是參與其中的好方法。然而，人們很難找到會議網址。大多數新貢獻者會在 #sig-docs 頻道提問，但我決定在文件中查詢會議資訊。這需要跨多個頁面點選多次。有多少新貢獻者因為找不到會議詳情而錯過了會議？

觀察 05：耐心是一種美德

貢獻者可能需要等待數天才能獲得對大型 PR 的反饋。從提交到最終批准的過程可能需要數週而不是數天。原因有二：1）大多數審閱者在 SIG Docs 上是兼職工作；2）審閱者希望提供有意義的審閱。“隨手審閱”在 SIG Docs 中是不存在的！審閱者會檢查以下內容：

  • 提交資訊和 PR 描述是否充分描述了更改？

  • PR 是否遵循樣式和內容指南中的指導原則？

    • 總的來說，語法和標點符號是否正確？
    • 內容是否清晰、簡潔，並且適合非母語人士閱讀？
    • 內容風格是否與文件其餘部分保持一致？
    • 內容流程是否合理？
    • 是否可以更改任何內容以使內容更好，例如使用 Hugo 短程式碼？
    • 內容是否正確渲染？

  • 內容在技術上是否正確？

有時審查過程讓我感到防禦、惱火和沮喪。我確信其他貢獻者也有同感。貢獻者需要耐心！編寫優秀的文件是一個迭代過程。審查者仔細審查 PR 是因為他們希望保持文件的高質量，而不是因為他們想惹惱貢獻者！

觀察 06：惜字如金

非英語母語者閱讀並貢獻 Kubernetes 文件。在撰寫內容時，請使用簡潔明瞭的語言和清晰簡潔的句子。您寫的每個句子都可能被翻譯成其他語言，因此請刪除不增加實質內容的詞語。我承認，有時實施這些準則具有挑戰性。

問題和拉取請求不會被翻譯成其他語言。但是，在編寫問題或拉取請求的描述時，您仍然應該遵循上述準則。您應該為問題新增詳細資訊和背景資訊，以便分流人員不必應用 `triage/needs-information` 標籤。同樣，當您建立拉取請求時，您應該新增足夠多的關於內容更改的資訊，以便審閱者不必費力找出拉取請求的原因。以清晰簡潔的語言提供詳細資訊可以加快流程。

觀察 07：分流問題比預想的要困難

在 SIG Docs 中，對問題進行分類需要能夠區分支援請求、錯誤報告和功能請求，不僅針對文件，還針對 Kubernetes 程式碼專案。周復一週，如何路由、標記和確定問題的優先順序變得越來越容易。我仍然不完全清楚哪個 SIG 和/或專案負責文件的哪些部分。SIG 和工作組頁面有所幫助，但這還不夠。在文件的頁面級別，哪個 SIG 或專案具有領域專業知識並不總是顯而易見的。頁面的前言有時會列出審閱者，但從不列出 SIG 或專案。每個頁面都應指明誰負責內容，以便 SIG Docs 分流人員知道如何路由問題。

觀察 08：SIG Docs 人手不足

文件是軟體採用的首要驅動因素1。

許多貢獻者在 SIG Docs 上投入少量時間，但只有少數是受過培訓的技術文件撰寫人員。很少有公司僱傭技術文件撰寫人員至少兼職在 Kubernetes 文件上工作。這對於線上文件來說非常令人沮喪，因為該文件在 2019 年迄今已吸引了來自 229 個國家的讀者超過 5300 萬獨立頁面瀏覽量。

由於缺乏技術寫作人員，SIG Docs 面臨挑戰

  • **維護 Kubernetes 文件的高質量**：文件超過 750 頁。這意味著需要定期檢查**750 頁**的過期內容。這不僅僅是針對 `kubernetes/website` 倉庫執行連結檢查器。這涉及到人員對 Kubernetes 具備技術理解，瞭解哪些程式碼釋出更改會影響文件，以及知道內容在文件中的位置，以便**所有**受影響的頁面和示例程式碼檔案都能及時更新。其他 SIG 會為此提供幫助，但根據讀者建立的問題數量來看，沒有足夠的人員致力於保持內容的新鮮度。
  • **縮短 PR 審查和合並時間**：PR 越大，獲得 `lgtm` 標籤和最終批准所需的時間就越長。我的 `size/M` 及更大的 PR 需要五到三十天才能獲得批准。有時我會禮貌地提醒審查員在我推送更新後再次審查。其他時候我會在 #sig-docs 頻道尋求**任何批准者**的檢視和批准。人們都很忙。人們會去度假。人們還會轉到不涉及 SIG Docs 的新職位，並忘記將自己從審查員和批准者分配檔案中刪除。導致合併時間過長的一個重要原因是審查員和批准者不足。另一個原因是成為審查員或批准者的高門檻，遠高於我在其他開源專案中看到的。經驗豐富的開源技術寫作人員即使想為 SIG Docs 貢獻，也無法快速獲得批准者和審查員的角色。一方面，高門檻確保了這些角色由具備最低 Kubernetes 文件知識的人員擔任；另一方面，它可能會阻止經驗豐富的技術寫作人員完全不參與貢獻，或者公司不將技術寫作人員分配給 SIG Docs。也許 SIG Docs 應該考慮偏離 Kubernetes 社群的要求，在個案基礎上降低成為審查員或批准者的門檻。
  • **確保所有頁面命名一致**：術語應與**標準化詞彙表**中使用的術語相同。保持一致性可減少混淆。查詢和修復這些情況非常耗時，但對讀者來說是值得的。
  • **與指導委員會合作制定專案文件指南**：Kubernetes 倉庫指南根本沒有提及文件。在專案的 GitHub 文件和 Kubernetes 文件之間，有些專案的內容幾乎重複，而另一些專案的內容則相互衝突。制定清晰的指南，以便專案知道將路線圖、里程碑和全面的功能詳細資訊放在 `kubernetes/<project>` 倉庫中，並將安裝、配置、使用詳情和教程放在 Kubernetes 文件中。
  • **刪除重複內容**：Kubernetes 使用者安裝 Docker，因此重複內容的一個很好的例子是 Docker 安裝說明。與其重複 Docker 文件中的內容，不如說明哪個版本的 Docker 與哪個版本的 Kubernetes 相容，並連結到 Docker 文件進行安裝。然後詳細說明任何 Kubernetes 特定的配置。這個想法對於 Kubernetes 支援的容器執行時也同樣適用。
  • **移除第三方供應商內容**：這與移除重複內容緊密相關。一些第三方內容包括詳細介紹外部產品列表或表格。其他第三方內容存在於**任務**和**教程**部分。SIG Docs 不應負責驗證第三方產品是否與最新版本的 Kubernetes 相容。SIG Docs 也不應負責維護培訓課程或雲提供商的列表。此外，Kubernetes 文件不是推銷供應商產品的地方。如果 SIG Docs 被迫改變其不允許第三方內容的政策，可能會出現大量供應商或商業性質的拉取請求。維護這些內容給 SIG Docs 帶來了不應有的負擔。
  • **指明每個任務和教程適用的 Kubernetes 版本**：這意味著需要審查每個版本中的每個任務和教程。讀者會假設，如果某個任務或教程存在於最新版本的文件中，那麼它就適用於最新版本的 Kubernetes。
  • **解決問題**：`kubernetes/website` 倉庫中有 470 個未解決的問題。很難跟上所有建立的問題。我們鼓勵那些建立更簡單問題的人提交 PR：有些人會這樣做；大多數人不會。
  • **建立更詳細的內容**：讀者表示他們希望在文件的所有部分，包括教程中，看到更詳細的內容。

Kubernetes 自 2015 年首次釋出以來，經歷了前所未有的增長。和任何快速發展的專案一樣，它也有成長的煩惱。提供始終如一的高質量文件就是其中一個煩惱，也是一個對開源專案來說極其重要的煩惱。SIG Docs 需要一個更大的核心技術寫作團隊，至少分配 50% 的時間。這樣，SIG Docs 就能更好地實現目標，推進新內容，更新現有內容，並及時解決未解決的問題。

觀察 09：貢獻技術文件專案平均需要比開發軟體更多的技能

當我對我以前的同事這麼說時，他們的反應是健康的懷疑和許多笑聲。似乎許多開發人員和經理都不完全瞭解技術寫作者為開源專案貢獻的實際工作。在從事開發和技術寫作 22 年的大部分時間裡，我注意到技術寫作者的價值遠低於同等水平的軟體開發人員。

SIG Docs 核心團隊成員所做的工作遠不止根據需求撰寫內容

  • 我們使用與開發人員相同的某些流程和工具，例如終端、git 工作流、GitHub 以及 Atom、Golang 和 Visual Studio Code 等 IDE；我們還使用文件特定的外掛和工具。
  • 我們對細節以及設計和組織有敏銳的洞察力：既有大局觀，也有微觀視角。
  • 我們提供具有邏輯流程的文件；它不僅僅是頁面上的內容，而是頁面如何融入章節，以及章節如何融入整體結構。
  • 我們撰寫內容全面，使用的語言能夠讓不精通英語的讀者理解。
  • 我們熟練掌握使用各種標記語言的英語寫作。
  • 我們是技術人員，有時達到 Kubernetes 管理員的水平。
  • 我們閱讀、理解並偶爾編寫程式碼。
  • 我們是專案經理，能夠規劃新工作並將問題分配到釋出版本。
  • 我們在每次審查和每次對問題發表評論時，都扮演著教育者和外交家的角色。
  • 我們利用網站分析，根據讀者最常訪問的頁面以及讀者認為無用的頁面來規劃工作。
  • 我們是調查員，定期徵求社群反饋。
  • 我們從整體上分析文件，根據可用資源和讀者需求，決定哪些內容應該保留，哪些內容應該刪除。
  • 我們掌握 Hugo 和其他用於線上文件的框架的實用知識；我們知道如何建立、使用和除錯 Hugo 短程式碼，使內容比純 Markdown 更健壯。
  • 我們不僅要解決 Hugo 的效能問題，還要解決 Netlify 的效能問題。
  • 我們努力解決 API 文件的複雜問題。
  • 我們致力於提供最高質量的文件。

如果您對 Kubernetes 文件專案的複雜性有任何疑問，請觀看 SIG Docs 主席 Zach Corleissen 的演講

此外，《程式碼即文件：缺失的手冊》（Jennifer Rondeau, Margaret Eker; 2016）是一份關於文件專案整體複雜性的優秀演示。

Write the Docs 網站和 YouTube 頻道是深入瞭解技術寫作的優點、缺點和弊端的好地方。

想象一下，如果沒有才華橫溢、盡職盡責的技術寫作人員，開源專案會是什麼樣子！

觀察 10：社群就是一切

SIG Docs 社群以及更廣闊的 Kubernetes 社群，致力於奉獻、聰明、友好、才華橫溢、充滿樂趣、樂於助人，以及許多其他積極的形容詞！人們張開雙臂歡迎我，不僅僅因為 SIG Docs 需要更多的技術寫作者。我從未覺得我的想法和貢獻因為我是新人而被忽視。謙遜和尊重至關重要。社群成員擁有豐富的知識可供分享。參加會議、提出問題、提出改進建議、感謝他人，並盡一切可能做出貢獻！

特別感謝在我磨合期幫助我並容忍我（哈哈）的各位：@zacharaysarah、@sftim、@kbhawkey、@jaypipes、@jrondeau、@jmangel、@bradtopol、@cody_clark、@thecrudge、@jaredb、@tengqm、@steveperry-53、@mrbobbytables、@cblecker 和 @kbarnard10。

結語

我是否深入理解了 SIG Docs？還沒有完全理解，但我確實明白 SIG Docs 需要更多專注的資源才能繼續取得成功。

參考文獻

1 @linuxfoundation。“Megan Byrd-Sanicki，開源策略師，谷歌 @megansanicki - 文件是軟體採用的第一驅動力。#ossummit。” Twitter，2019 年 10 月 29 日，上午 3:54，twitter.com/linuxfoundation/status/1189103201439637510。