本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。
專案摘要
- 開放原始碼組織：
- 雲端原生運算基金會 (CNCF)
- 技術撰稿人：
- Syam Sundar K
- 專案名稱：
- 更多更出色的 Kbectl 範例
- 專案長度：
- 標準長度 (3 個月)
Project description
本專案的動機是強化現有的 kubectl 速查表和參考文件。
以下是本專案的最終目標： • 建立更多且更優質的 kubectl 範例。• 在 kubectl 一覽表中新增 kubectl 範例。• 重構 kubectl 說明文件，以便提供最實用的資訊。
目標 I - kubectl 範例：
我們將與 CLI 特殊興趣群組密切合作，瞭解 Kubernetes 使用者想要獲得最多哪種範例，並記錄下來。這的範圍包括改善一覽表上現有的 kubectl 指令，以及在一覽表中新增指令。
目標 II：提高文件的實用性：
為了讓文件更實用，您可以採取下列做法：
• 消除初學者遇到的困難 • 按照特定順序重新排列 kubectl 指令，確保邏輯流程的連續性
透過更完善的指令 / 使用情境說明，消除初學者遇到的困難。這項功能看似簡單，但對初學者來說，這項功能會大幅影響他們是否繼續學習，舉例來說，當我透過 kubectl 開始使用 Kubernetes 時，不太清楚 Pod 和 Deployment 之間的差異。我一開始會部署以 nodejs 編寫的後端服務，幾小時後，我想關閉它，因此嘗試刪除 Pod，但由於 Pod 具有自我修復的特性，因此又重新建立了 Pod。我對發生的情況感到困惑，也想知道為什麼會重新建立而非刪除。在網路上查詢了幾次後，我發現刪除 Pod 與刪除部署作業不同。對訓練有素的眼睛來說，這可能很簡單，但清楚的說明可消除這類模糊不清之處，這就是好文件與優秀文件的差別。
以特定順序重新排列 kubectl 指令，確保邏輯流程的連續性。如果你和我一樣是故事敘述的忠實信徒，可能會想知道如何在包含終端機指令清單的文件工作表中加入故事敘述元素。我可以告訴你，這麼做是可行的。我們學習的任何事物都會有邏輯流程，也就是起點和終點。kubectl 做為指令列工具，顯然有一套學習曲線，事實上，它的學習過程與 Kubernetes 本身的學習曲線恰好相符。由於幾乎人人都可透過 kubectl (使用網頁版 UI 的人除外) 開始使用 Kubernetes。由於 Kubernetes 的學習曲線與 Kubernetes 的學習曲線緊密結合，因此只要變更這些指令的順序，並引入故事元素，就能大幅改善這個說明文件。舉例來說，您可以先解釋資源，然後再以實例和插圖說明水平 Pod 自動調度等功能。
目標 III - 改善文件的可用性：
近期將 Kubernetes 網站遷移至 Docsy Hugo 的做法非常棒，也是說明文件方面的重要轉變。雖然遷移作業已成功，但文件空間仍有許多進步空間。
以下是我建議的部分變更，
• 左側窗格會自動捲動至主要文件中目前處於活動狀態的部分，方便您追蹤目前、即將到來和已完成的部分。• 複製到剪貼簿：有些指令可能很長，在使用這類指令時，複製功能就很實用。• 文件檔案的內容格式 - 遷移後，部分頁面內容的格式未正確設定，例如 kubectl 總覽中的「Resource Type」部分。這會降低使用者體驗。
這些異動可改善 Kubernetes 網站的使用者體驗，並提升使用者工作效率。