在 Docs 中回顧 2019 年

嗨，各位！我是 Kubernetes 文件特殊興趣小組 (SIG Docs) 的共同主席之一。這篇部落格文章是對 2019 年 SIG Docs 的回顧。我們的貢獻者去年做了出色的工作，我想強調他們的成功。

雖然我在這篇文章中回顧 2019 年，但我的目標是指向 2020 年。我觀察到 SIG Docs 的一些趨勢 - 有些是好的，有些則令人擔憂。我想在這些挑戰變得更加嚴重之前提高能見度。

好的方面

2019 年 SIG Docs 有許多值得慶祝的事情。

Kubernetes 文件在年初有三個本地化正在進行中。到年底，我們結束時有十個本地化版本可用，其中四個（中文、法文、日文、韓文）相當完整。韓文和法文團隊值得特別表揚，他們對所有本地化的 git 最佳實踐（韓文團隊）以及協助啟動其他本地化（法文團隊）做出了貢獻。

儘管這一年經歷了重大的轉型，但 SIG Docs 提高了審查速度，從 PR 開啟到合併的中位數審查時間僅略超過 24 小時。

問題分類在數量和速度方面都顯著改善，這主要歸功於 GitHub 使用者 @sftim、@tengqm 和 @kbhawkey 的努力。

文件衝刺在 KubeCon 貢獻者日仍然很有價值，為 Kubernetes 文件介紹了新的貢獻者。

Kubernetes 季度發布的文件組件在 2019 年期間得到改進，這要歸功於發布負責人及其團隊對劇本的迭代改進。

網站流量在這一年中有所增加。該網站年底的 12 月每月頁面瀏覽量約為 600 萬次，高於 1 月份的約 500 萬次。kubernetes.io 網站 10 月份的網站訪客為 85.1 萬人次，創下歷史新高。讀者滿意度總體保持。

我們迎來了一位新的 SIG 主席：@jimangel，通用汽車公司的雲端架構師。Jim 在擔任主席之前，曾擔任文件貢獻者一年，期間他領導了 1.14 文件發布。

不太好的方面

雖然讀者滿意度還不錯，但大多數受訪者表示對每個領域（概念、任務、教學和參考）中的過時內容不滿意。此外，讀者要求更多圖表、進階概念內容和程式碼範例 - 這些都是技術寫作人員擅長提供的。

SIG Docs 繼續解決如何最好地處理第三方內容。kubernetes.io 上有太多供應商內容，而且添加或拒絕第三方內容的指南仍然不明確。到目前為止的討論非常有力，包括要求更多協作投入的反對意見 - 這有力地提醒我們，Kubernetes 在各方面都是社群共同努力的成果。

我們正處於 18 個月內的第三次主席過渡期。每次主席過渡都很健康且融洽，但在短時間內仍然有很多更替。主持任何開源專案都很困難，對於 SIG Docs 尤其如此。SIG Docs 的主席職位需要跨多個領域的陡峭學習曲線：文件（書面文件和從規格產生的文件）、資訊架構、專業的貢獻途徑（例如，本地化）、如何運行發布週期、網站開發、CI/CD、社群管理等等。這是一個需要多人才能成功運作的角色，而不會讓人們精疲力盡。培訓接替者非常耗時。

在「不太好」類別中，也許最迫切的是 SIG Docs 目前只有一位技術寫作人員全職投入 Kubernetes 文件工作。這對 Kubernetes 文件產生了一些影響：有些是顯而易見的，有些則不太明顯。

人手不足對 Kubernetes 文件的影響

今天的我：pic.twitter.com/cDpHOWEsjf

— Benjamin Elder (@BenTheElder) 2020 年 1 月 10 日

如果 Kubernetes 在 2020 年繼續沒有更多技術寫作人員投入文件工作，以下是我認為最有可能發生的情況。

但首先，免責聲明

我的一些預測幾乎肯定會出錯。任何錯誤都僅由我個人承擔。

話雖如此...

2020 年的影響

目前的功能水平無法自我維持。即使有強大的劇本，發布週期仍然需要至少一位（通常是兩位）主席在每個週期中提供專家支援。毫無例外，每次發布都會以新的且意想不到的方式出錯，並且需要熟悉度和專業知識來診斷和解決。隨著主席繼續輪換 - 需要明確的是，定期過渡是一個健康專案的一部分 - 我們累積了與缺乏足夠專業深度和雇主支持的人才庫相關的風險。

奇怪的是，人員配置的挑戰之一是文件看起來已經足夠好了。基於網站分析和調查回覆，讀者對文件品質感到滿意。當人們訪問網站時，他們通常會找到他們需要的東西，並且表現得像滿意的訪客。

危險在於這種情況會隨著時間推移而改變：最初是緩慢地伴隨著偶爾的功能喪失，起初令人惱火，然後變得越來越關鍵。在沒有足夠人員配置的情況下，時間越長，修復將變得越困難和昂貴。

我懷疑這是真的，因為我們現在在讀者滿意度還不錯的情況下所面臨的挑戰已經很難解決。API 參考文檔生成既複雜又脆弱；網站的 UI 已過時；而且我們最常收到的請求是更多教學、進階概念、圖表和程式碼範例，所有這些都需要持續的、專門的時間來創建。

發布支援仍然強大。

發布團隊繼續保持良好的習慣，為每個接替團隊留下比上一個版本更好的支援。這主要以迭代改進文件發布劇本的形式呈現，產生更好的文檔並減少孤島知識。

過時加速。

隨著功能更改或棄用，概念內容變得不太準確或相關。教學內容也因同樣原因而退化。

內容結構也將退化：概念、任務和教學的類別是遺留類別，可能不最適合當前讀者的需求，更不用說未來的讀者了。

對於讀者和貢獻者來說，雜亂的東西都會累積。參考文檔在沒有干預的情況下變得越來越脆弱。

關鍵知識消失。

正如我之前提到的，SIG Docs 具有廣泛的功能，其中一些功能具有陡峭的學習曲線。隨著貢獻者更換角色或工作，他們的專業知識和可用性將會減少或降至零。具有特定知識的貢獻者可能無法提供諮詢，從而暴露文件功能中的關鍵漏洞。具體範例包括參考文檔生成和主席領導。

這信息量很大

很難在 SIG Docs 的工作對社群和使用者的重要性、它個人帶給我的樂趣，以及事物不能保持原樣而不產生重大負面影響（最終）之間取得平衡。SIG Docs 絕非正在消亡；它是一個充滿活力的社群，有活躍的貢獻者在做很酷的事情。它也是一個社群，存在一些關鍵知識和能力短缺問題，這些問題只能透過訓練有素的、專門從事文檔工作的有薪員工來解決。

社群可以為健康的文件做些什麼

聘請專門從事 Kubernetes 文件的技術寫作人員。支援進階內容創建，而不僅僅是發布文檔和增量功能更新。

謝謝，新年快樂 2020 年。

• ←上一篇
下一篇→