Grokkin' 文件

簡介 - 一位新任 SIG Docs 貢獻者的觀察

我於 2019 年 8 月開始為 SIG Docs 社群做出貢獻。有時我覺得自己像個身處異鄉的陌生人，正在適應一個新的社群：研究社群組織、了解貢獻者社群、學習新的經驗，以及融入新的術語。我既是觀察者也是貢獻者。

觀察 01：閱讀「貢獻」頁面！

我曾為 OpenStack、OPNFV 和 Acumos 貢獻程式碼和文件，所以我認為為 Kubernetes 文件做出貢獻也會是同樣的情況。我錯了。我應該徹底閱讀 Kubernetes 文件貢獻指南 頁面，而不是略讀它們。

我非常熟悉 git/gerrit 工作流程。使用這些工具，貢獻者會複製 master 儲存庫，然後建立一個本地分支。Kubernetes 使用不同的方法，稱為「Fork and Pull」。每個貢獻者都 forks master 儲存庫，然後貢獻者將工作推送到他們的分支，然後再建立提取請求。我按照「開始貢獻」頁面中 提交提取請求 區段中的說明，建立了一個簡單的提取請求 (PR)。本節說明如何使用 GitHub UI 進行文件變更。我了解到這種方法適用於只需要單次提交即可修復的變更。但是，當您需要對 PR 進行額外更新時，此方法會變得複雜。GitHub 會為使用 GitHub UI 進行的每個變更建立一個新的提交。Kubernetes GitHub 組織要求壓縮提交。 「開始貢獻」頁面沒有提及壓縮提交，所以我查看了 GitHub 和 git 文件。我無法使用 GitHub UI 壓縮我的提交。我必須在本地 git fetch 和 git checkout 我的提取請求，使用命令列壓縮提交，然後推送我的變更。如果「開始貢獻」頁面有提及壓縮提交，我會從本地副本開始工作，而不是使用 GitHub UI。

觀察 02：主動聯繫並 ping 某人

在處理我的第一個 PR 時，我對從本地副本工作以及如何讓我的分支與 upstream master 保持同步有疑問。我轉向在網路上搜尋，而不是在 Kubernetes Slack #sig-docs 頻道上提問。我使用了錯誤的流程來更新我的分支，所以我必須 git rebase 我的 PR，結果非常不順利。因此，我關閉了那些 PR 並提交了新的 PR。當我在 #sig-docs 頻道上尋求幫助時，貢獻者發布了有用的連結、我的本地 git config 檔案應該是什麼樣子，以及要運行的確切 git 命令集。貢獻者使用的流程與「中階貢獻」頁面中定義的流程不同。如果我問一下應該使用哪個 GitHub 工作流程，我本可以節省很多時間。社群知識記錄得越多，新貢獻者就越容易快速地提高生產力。

觀察 03：不要讓衝突的資訊破壞您的一天

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

觀察 04：資訊可能分散

大型開源專案的資訊分散在各個儲存庫中或在儲存庫之間重複是很常見的。有時團隊在各自的領域中工作，並且資訊沒有共享。有時，一個人離開去從事不同的專案，而沒有傳遞專業知識。由於優先級較高的項目，文件缺口仍然存在，並且可能永遠無法彌補。因此，新的貢獻者可能難以找到基本資訊，例如會議詳細資訊。

參加 SIG Docs 會議是參與其中的好方法。但是，人們很難找到會議 URL。大多數新貢獻者會在 #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 或專案具有領域專業知識並不總是顯而易見的。頁面的 front matter 有時會列出審閱者，但從未列出 SIG 或專案。每個頁面都應指示誰負責內容，以便 SIG Docs 分流人員知道將問題路由到哪裡。

觀察 08：SIG Docs 人員不足

文件是軟體採用的首要驅動力¹。

許多貢獻者只花少量時間在 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：有些人這樣做，但大多數人沒有。
• 建立更詳細的內容：讀者表示他們希望看到文件中所有章節（包括教學課程）都有更詳細的內容。

自 2015 年首次發布以來，Kubernetes 見證了前所未有的成長。與任何快速成長的專案一樣，它也有成長的煩惱。提供始終如一的高品質文件就是其中一個煩惱，而且對於開放原始碼專案來說，這是一個非常重要的煩惱。SIG Docs 需要一個更大的技術寫作者核心團隊，這些技術寫作者至少需要投入 50% 的時間。然後，SIG Docs 才能更好地實現目標、推進新內容、更新現有內容，並及時處理未解決的議題。

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

當我對以前的同事說這句話時，他們的回應是健康的懷疑和許多笑聲。似乎許多開發人員以及經理並不完全了解貢獻開放原始碼專案的技術寫作者實際上在做什麼。在從事開發和技術寫作工作 22 年的大部分時間裡，我注意到技術寫作者的價值遠低於同等地位的軟體開發人員。

SIG Docs 核心團隊成員所做的不僅僅是根據需求撰寫內容

• 我們使用與開發人員相同的一些流程和工具，例如終端機、git 工作流程、GitHub 和 IDE（例如 Atom、Golang 和 Visual Studio Code）；我們也使用文件特定的外掛程式和工具。
• 我們在細節以及設計和組織方面都具有良好的眼光：大局和小細節。
• 我們提供的文件具有邏輯流程；它不僅僅是頁面上的內容，更是頁面如何融入章節，以及章節如何融入整體結構。
• 我們撰寫內容全面且使用的語言，讓不精通英語的讀者也能理解。
• 我們精通使用各種標記語言的英語寫作。
• 我們在技術方面很專業，有時達到 Kubernetes 管理員的程度。
• 我們會閱讀、理解，偶爾也會撰寫程式碼。
• 我們是專案經理，能夠規劃新工作以及將議題指派給版本。
• 我們是教育家和外交官，每次審閱和在議題上留下的每則評論都是如此。
• 我們使用網站分析來根據讀者最常存取的頁面以及讀者表示無用的頁面來規劃工作。
• 我們是調查員，定期向社群徵求意見回饋。
• 我們將文件視為一個整體進行分析，根據可用資源和讀者需求，決定哪些內容應該保留，哪些內容應該移除。
• 我們具備 Hugo 和其他用於線上文件的框架的工作知識；我們知道如何建立、使用和偵錯 Hugo 短代碼，這些短代碼使內容比純 Markdown 更強大。
• 我們不僅針對 Hugo，也針對 Netlify 進行效能問題的疑難排解。
• 我們致力於解決 API 文件的複雜問題。
• 我們致力於提供我們所能提供的最高品質的文件。

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

• 多語言 Kubernetes - kubernetes.io 堆疊、我們如何到達那裡，以及到達那裡需要什麼
• 翻譯中的發現：從一年的開放原始碼本地化中吸取的教訓

此外，文件即程式碼：遺失的手冊 (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 需要更多專門的資源才能繼續取得成功。

引用

¹ @linuxfoundation。「Megan Byrd-Sanicki，Google 開放原始碼策略師 @megansanicki - 文件是軟體採用的第一驅動力。#ossummit。」Twitter，2019 年 10 月 29 日，凌晨 3:54，twitter.com/linuxfoundation/status/1189103201439637510。

• ←上一篇
下一篇→