回顧 2019 年的文件工作

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

雖然本文回顧了 2019 年，但我的目標是展望 2020 年。我觀察到 SIG Docs 的一些趨勢——有些是好的，有些是令人擔憂的。我想在這些挑戰變得更加嚴峻之前提高可見性。

好的方面

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

Kubernetes 文件在年初有三個正在進行中的本地化。到年底，我們共有十個可用的本地化版本，其中四個（中文、法文、日文、韓文）相對完整。韓國團隊因其在所有本地化工作中對 Git 最佳實踐的貢獻（韓國團隊）以及幫助引導其他本地化工作（法國團隊）而值得特別提及。

儘管這一年經歷了重大轉變，SIG Docs 提高了其評審速度，從 PR 開放到合併的平均評審時間僅略超過 24 小時。

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

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

得益於釋出負責人及其團隊對操作手冊的迭代改進，2019 年 Kubernetes 季度釋出的文件元件有所改進。

網站流量在這一年有所增加。網站在 12 月結束時每月約有 600 萬頁面瀏覽量，高於 1 月份的約 500 萬頁面瀏覽量。kubernetes.io 網站在 10 月份有 85.1 萬獨立訪客，創下歷史新高。讀者滿意度 總體保持良好。

我們迎來了一位新的 SIG 主席：@jimangel，通用汽車的雲架構師。Jim 曾是 docs 貢獻者一年，期間他領導了 1.14 docs 釋出，之後擔任主席。

不太好的方面

雖然讀者的滿意度不錯，但**大多數受訪者表示對所有領域的過時內容感到不滿意**：概念、任務、教程和參考。此外，讀者還要求提供更多圖表、高階概念內容和程式碼示例——這些都是技術寫手擅長提供的。

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 年快樂。

• ←上一篇
• 下一篇→