改進 cert-manager 網站的導覽和結構

專案更新

2022 年 9 月 7 日：Webhook 除錯指南

在 Google Season of Docs 計畫開始時，我們為常見的使用者任務建立了摩擦日誌，例如除錯「connect: connection refused」錯誤。此任務的摩擦日誌，可在GSoD 工作文件中看到，目的是作為一個參考點，以了解我們旨在帶來的改進是否會產生影響。

摩擦日誌顯示一個一致的模式：使用者在 Google 上搜尋錯誤訊息，對於 GitHub 上沒有任何解決方案的問題感到困惑，然後點擊 Google 結果中的第二個連結，但沒有太大效果。我們意識到可以改進的一點是，在 FAQ 頁面中加入「Webhook 問題疑難排解」的連結。我們發現此 FAQ 頁面有兩個問題

1. 由於頁面上沒有列出錯誤訊息，導致任何人無法找到它，這表示 Google 不會在搜尋結果中顯示該頁面。
2. 頁面上沒有列出許多錯誤訊息。

我們著手重寫此頁面，目標是使其以錯誤為中心，這表示使用者只需尋找他們的特定錯誤並開始除錯。我們稱之為「cert-manager Webhook Pod 的權威除錯指南」，可以在這裡找到。

2022 年 8 月 12 日：改進了導覽選單的佈局

在顯示器尺寸 >=1280px 時，左側選單太窄，無法清楚顯示巢狀選單項目。在較小的顯示器上，響應式 CSS 實際上使選單更大。因此，我們在顯示器尺寸 >=1280px 時將其加寬 1 個欄位，並減少內容寬度 1 個欄位以作為補償。這使得選單在筆記型電腦和桌上型電腦螢幕上更易於閱讀。

我們修正了具有子選單的選單項目和沒有子選單的選單項目之間垂直間距不一致的問題。

最後，我們將版本選擇器移至側邊欄底部，以避免分散讀者的注意力。

2022 年 8 月 3 日：cert-manager.io 文件調查已結束

感謝所有參與我們文件調查的人。我們將使用結果來優先考慮網站的哪些部分需要重組和重寫。在本 Season-of-Docs 結束之前，我們將從回覆中選出一位隨機獲獎者，並與您聯繫有關您的獎品事宜。

2022 年 7 月 18 日：cert-manager.io 文件調查

我們創建了一份簡短的調查，以幫助我們確定 cert-manager.io 文件最重要的優先事項。

1. 我們希望找出最有用的文件，這樣我們就不會去更改那些已經運作良好的部分。
2. 我們想知道哪些文件沒有用處，以便我們可以進行改進。
3. 我們希望聽到新使用者和有經驗的使用者，關於您們如何以及多久使用文件的意見。
4. 我們也想知道您在哪裡可以找到關於 cert-manager 的好資訊，在 cert-manager.io 網站之外，這樣我們就可以嘗試納入一些這些來源。

我們已將調查的連結添加到本網站頂部的橫幅中，我們也將在我們的 Slack 頻道和郵件清單中分享該連結。

請花 10 分鐘填寫調查.

2022 年 7 月 15 日：新的「入門」頁面

我們一直在審核現有的文件，以確定我們的使用者和潛在的新使用者需要執行的關鍵任務。我們為其中一些任務創建了「摩擦日誌」。這意味著我們假設自己處於使用者的位置並詢問，例如，

如何在 Kubernetes 中為我的伺服器取得 Let's Encrypt 憑證？

因此，我們在 Google 和 DuckDuckGo 上搜尋「Let's Encrypt Kubernetes」，令我們驚訝的是，cert-manager.io 沒有出現在頂部的搜尋結果中。

在搜尋結果中，有一些關於使用 cert-manager 創建 Let's Encrypt 憑證的優秀第三方教學和影片，我們感謝作者花時間撰寫如此詳細的內容。但不可避免地，其中一些參考了較舊版本的 cert-manager 和 Kubernetes。因此，我們決定為 cert-manager.io 網站編寫一些官方指南，示範如何快速安裝 cert-manager 並為 Let's Encrypt 進行設定。我們希望隨著時間的推移，這些指南將被搜尋引擎索引，並在「Let's Encrypt Kubernetes」的搜尋結果中名列前茅。優點是使用者和潛在的使用者將找到最新的資訊，並且 cert-manager.io 維護者將收到較少來自嘗試此任務的新使用者的支援請求。

前往閱讀新的GKE 使用者入門指南，並告訴我們您的想法。

2022 年 5 月 5 日：宣布 Mehak Saeed 擔任技術寫手

我們很高興宣布 Mehak Saeed 將擔任此專案的技術寫手。Mehak 在面試中的簡報給我們留下了深刻的印象，我們對她詳細的準備和規劃印象深刻。我們期待與她合作。

感謝所有其他申請此專案的技術寫手。

2022 年 4 月 14 日：專案已接受

此專案於 2022 年 4 月 14 日被接受。

2022 年 3 月 24 日：專案已註冊

我們已註冊我們對參與 Google Season of Docs 2022 的興趣，並提交了此頁面其餘部分詳細說明的單一專案提案。

您必須在 2022 年 4 月 27 日 18:00 UTC 之前申請技術寫手職位。

我們將於 2022 年 5 月 4 日星期三下午 15:00 (倫敦時間) (14:00 UTC) 在 Slack 的 #cert-manager-dev 頻道中分享選定候選人的姓名。

若要申請成為技術寫手，請透過以下兩種方式之一通知我們

• 寄電子郵件至 cert-manager-maintainers@googlegroups.com，並在電子郵件主旨中加上前綴 GSoD2022:。
• 或在 cert-manager/website 上開啟一個問題，並在問題標題中加上前綴 GSoD2022:。

您可以參加我們的公開站立會議 (每天英國時間 10:30)，並加入 Kubernetes Slack 頻道 #cert-manager-dev，以瞭解更多關於此專案提案的資訊。

關於 cert-manager

cert-manager (目前版本 1.8.0，於 2017 年 10 月首次發布) 是一個 Apache-2.0 許可的 Kubernetes 外掛程式，用於自動化 TLS 憑證的管理和發行。

我們典型的貢獻者是來自世界各地的 Go 開發人員，他們具有 Kubernetes 生態系統的經驗，並且具有為核心 Kubernetes 元件和 Kubernetes 運算子做出貢獻的經驗。

我們的使用者通常是開發人員和系統管理員，他們試圖自動化在 Kubernetes 叢集中執行的應用程式的 TLS 憑證輪換。

我們最大的使用者在多個 Kubernetes 叢集上安裝了 cert-manager，並管理著數千個 TLS 憑證。

專案概述

目前內容的設計並未考量到我們的目標受眾。例如，新使用者無法輕易找到說明如何在 AWS 上安裝 cert-manager 並針對 Let's Encrypt 進行設定的指南。同樣地，叢集管理員也無法輕易找到關於如何針對具有大量憑證的大型叢集最佳化 cert-manager 的資訊。這些資訊存在，但分散在多個頁面中，而且通常不在明顯的位置。

舉例來說，當使用者尋找關於如何使用 Certificate 資源的指南時，可能會在發現「Certificate」頁面存在兩次（一次在「使用方式」部分，另一次在「概念」部分）時感到無助。

(注意：此螢幕截圖來自我們舊的網站設計，但文字和版面配置大致相同)

我們希望一位技術寫手

1. 協助我們識別目標受眾，並且
2. 識別每個受眾的關鍵任務，並且
3. 以此為基礎重新組織 cert-manager.io 網站。

例如，我們討論了以下受眾和任務：初學者、叢集管理員、使用者、整合者、新貢獻者，而每個人都會對不同的任務集感興趣。我們希望他們能夠快速且輕鬆地找到他們需要的資訊。

透過讓每個群體更容易找到他們需要的資訊，我們的目標是減少支援查詢的數量。

受眾

新使用者

從未使用過 cert-manager，甚至可能從未使用過 Kubernetes。想要了解 cert-manager 可以提供什麼。可能在其他教學中聽說過 cert-manager。可能想知道 cert-manager 的替代方案以及優缺點。需要快速安裝 cert-manager，以便在筆記型電腦上進行評估。需要學習 cert-manager 的基本設定。需要了解接下來的步驟。

持續使用者

一位想要部署受 TLS 保護應用程式的程式設計師。知道 cert-manager 已由其叢集管理員安裝。具有現有的 Issuer 或 ClusterIssuer。需要知道如何建立適合其應用程式的憑證。例如：

• 為其 PostgreSQL 資料庫建立憑證
• 為其 Ingress/Gateway 建立憑證。需要知道如何偵錯憑證未更新的原因。需要了解 cert-manager 憑證和憑證請求上的錯誤訊息。需要知道他們可以修復哪些錯誤，以及哪些錯誤需要叢集管理員的協助。

叢集管理員

了解 Kubernetes。擁有長期執行的 cert-manager 安裝。想要了解如何設定和升級它以獲得最佳效能。想要針對大量憑證進行最佳化。想要從較舊版本升級。想要監控 cert-manager 的效能。想要設定警示，以便在 cert-manager 出錯時通知他們。可能想要針對多個雲端供應商設定 cert-manager。可能想要讓 cert-manager 與其他叢集範圍的系統（例如 Istio 或 Knative）一起運作。

整合者

可能想要允許 cert-manager 使用者使用自訂憑證服務。可能想要將 cert-manager 與 ACME DNS01 的 DNS API 整合。可能想要依賴 cert-manager 來管理較高層級系統的 TLS 憑證。需要學習如何為 cert-manager 編寫外掛程式/擴充功能。需要外掛程式和擴充功能的最新範例連結。

新貢獻者

想要回報 cert-manager 中的錯誤。想要修復 cert-manager 中的錯誤。想要為 cert-manager 提出功能建議。想要為 cert-manager 實作功能。需要學習如何瀏覽 cert-manager 程式碼。學習 cert-manager 程式碼標準和風格。需要知道如何執行 cert-manager 的測試。

範圍

此專案的範圍如下：

1. 識別並描述三個目標受眾。
2. 識別每個受眾的三個關鍵首要任務。
3. 稽核現有文件，並建立目前文件的摩擦日誌。
4. 以摩擦日誌作為基準，重新組織文件以最大程度地減少三個首要任務的摩擦。
5. 納入文件測試人員（專案中的志願者）和更廣泛的 cert-manager 社群的回饋。
6. 與 cert-manager 團隊合作，將文件發佈在 cert-manager.io 上。
7. 為網站貢獻者建立文件，說明我們如何圍繞受眾和任務來組織內容。

衡量成功

在技術寫手協助我們識別每個受眾的 3 個關鍵任務後，我們將衡量完成任務所需的點擊次數的基準，並且我們將努力減少每個任務的點擊次數。

時程表

日期	行動項目
五月	概況介紹
五月/六月	識別受眾和任務
五月/六月	稽核和摩擦日誌
六月	重組任務
六月/七月	納入回饋
六月/七月	發佈到 cert-manager.io
七月	完成網站貢獻者指南的撰寫
七月	專案完成

預算

預算項目	金額 ($)	累計金額 ($)	備註
技術寫手稽核和重組 cert-manager.io 文件	12,000	12,000
志願者津貼	1,500	13,500	3 位志願者津貼 x 每位 500 美元
總計		13,500

關於 12,000 美元的金額，我們假設它足以資助一位有經驗的技術寫手兼職（例如，他們可以在星期二到星期五工作半天，總共 24 天，為期 3 個月，每日費率為 500 美元）。

我們將向在專案時程（從 5 月 1 日到 7 月 30 日）內證明他們在其中一個 PR 中重新撰寫一頁或一組頁面的貢獻者提供「志願者津貼」。在開始重新撰寫之前，志願者將在 Slack (Kubernetes Slack，頻道 #cert-manager-dev) 或 GitHub 上的 issue 中建議他們希望處理哪個頁面，並透過詢問團隊來確保重新處理此頁面是否有意義。只要至少有一個正面反應，志願者就可以開始工作。為了使津貼生效，PR 需要經過審閱並合併。