cert-manager ウェブサイトのナビゲーションと構造を改善する
プロジェクトの最新情報
2022年9月7日：Webhook デバッグガイド
Google Season of Docs プログラムの開始時に、私たちは「connect: connection refused」エラーのデバッグなど、一般的なユーザータスクの摩擦ログを作成しました。このタスクの摩擦ログは、GSoD 作業ドキュメントに記載されており、私たちが目指す改善が影響を与えるかどうかを確認するための基準点として機能しました。
摩擦ログは一貫したパターンを示しました。ユーザーはGoogleでエラーを検索し、解決策のないGitHubのissueに混乱し、あまり運がないままにGoogleの結果の2番目のリンクをクリックします。私たちは、FAQページの「Webhookに関する問題のトラブルシューティング」へのリンクを追加することが1つの改善点になることに気づきました。このFAQページには2つの問題がありました。
- エラーメッセージがページにリストされていなかったため、誰もそれを見つけることができませんでした。つまり、Googleは検索結果にページを表示しませんでした。
- 多くのエラーメッセージがページにリストされていませんでした。
私たちはこのページをエラーに焦点を当てて書き直すことにしました。つまり、ユーザーは特定のエラーを探し、デバッグを開始できるようにすることを目指しました。私たちはそれを「cert-manager Webhook Pod のための決定的なデバッグガイド」と呼び、こちらで見つけることができます。
2022年8月12日：ナビゲーションメニューのレイアウトを改善しました
ディスプレイ >=1280px では、左側のメニューが狭すぎて、ネストされたメニュー項目を明確に表示できませんでした。小さなディスプレイでは、レスポンシブCSSが実際にメニューを大きくしていました。そこで、ディスプレイ >=1280px でメニューを1列広げ、コンテンツの幅を1列減らして補正しました。これにより、ラップトップやデスクトップコンピュータの画面でメニューがはるかに読みやすくなります。
サブメニューのあるメニュー項目とないメニュー項目の間の垂直方向の間隔の不整合を修正しました。
そして最後に、読者の気を散らさないように、バージョンセレクターをサイドバーの下部に移動しました。
2022年8月3日：cert-manager.io ドキュメントアンケートは終了しました
ドキュメントアンケートにご協力いただいた皆様、ありがとうございました。結果をもとに、Webサイトの再構築と書き換えを優先するセクションを決定します。このSeason-of-Docsの終了までに、回答の中からランダムに当選者を選出し、賞品についてご連絡します。
2022年7月18日：cert-manager.io ドキュメントアンケート
cert-manager.ioドキュメントの最優先事項を特定するのに役立つ短いアンケートを作成しました。
- 私たちは、すでにうまく機能しているものを変更しないように、最も役立つドキュメントを特定したいと考えています。
- 改善のために、どのドキュメントが役に立たないかを知りたいと考えています。
- 新規ユーザーと経験豊富なユーザーの両方から、ドキュメントをどのように、どのくらいの頻度で使用しているかについてお話を伺いたいと思います。
- また、cert-manager.io Webサイト以外でcert-managerに関する良い情報を見つけた場所を知りたいので、それらの情報源を取り入れられるようにしたいと考えています。
このサイトの上部のバナーにアンケートへのリンクを追加しました。また、Slackチャンネルとメーリングリストでもリンクを共有します。
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 Webサイト用に、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 で共有します。
テクニカルライターとして応募するには、以下の2つのいずれかの方法でお知らせください。
- 件名に
GSoD2022:のプレフィックスを付けて、cert-manager-maintainers@googlegroups.comまでメールでお知らせください。 - または、issueタイトルに
GSoD2022:のプレフィックスを付けて、cert-manager/website にissueを開いてください。
私たちのオープンスタンドアップ（毎日英国時間10:30）に参加し、Kubernetes Slackチャンネル #cert-manager-dev に参加して、このプロジェクト提案について詳しく知ることができます。
cert-managerについて
cert-manager（現在のバージョン1.8.0、2017年10月に最初のリリース）は、TLS証明書の管理と発行を自動化するためのApache-2.0ライセンスのKubernetesアドオンです。
私たちの典型的な貢献者は、Kubernetesエコシステムでの経験があり、コアKubernetesコンポーネントおよびKubernetesオペレーターへの貢献経験を持つ世界中のGo開発者です。
私たちのユーザーは、Kubernetesクラスターで実行されているアプリケーションのTLS証明書のローテーションを自動化しようとしている開発者およびシステム管理者であることがよくあります。
最大規模のユーザーは、複数のKubernetesクラスターにcert-managerをインストールし、数千のTLS証明書を管理しています。
プロジェクト概要
現在、コンテンツはターゲットオーディエンスを念頭に置いて設計されていません。たとえば、新規ユーザーは、AWSにcert-managerをインストールし、Let's Encrypt用に構成する方法を説明するガイドを簡単に見つけることができません。また、クラスター管理者も、多数の証明書を持つ大規模クラスター向けにcert-managerを最適化する方法に関する情報を簡単に見つけることができません。情報は存在しますが、複数のページに分散しており、多くの場合、見つけやすいページにありません。
視覚的な例として、Certificateリソースの使用方法に関するガイドを探しているユーザーは、「Certificate」ページが「使用法」セクションと「概念」セクションの両方に存在することに気づいたとき、途方に暮れるかもしれません。
（注：このスクリーンショットは古いサイトデザインのものですが、テキストとレイアウトはほぼ同じです）
技術ライターを求めています。
- ターゲットオーディエンスを特定し、
- これらのオーディエンスそれぞれの主要なタスクを特定し、
- これを念頭に置いてcert-manager.ioのWebサイトを再構成してもらいたいと考えています。
たとえば、初心者、クラスター管理者、ユーザー、インテグレーター、新規コントリビューターなどのオーディエンスとタスクについて話し合ってきました。これらの人々はそれぞれ異なるタスクに関心があるでしょう。彼らが必要な情報を迅速かつ簡単に見つけられるようにしたいと考えています。
各グループが必要な情報を簡単に見つけられるようにすることで、サポートクエリの数を減らすことを目指しています。
対象者
新規ユーザー
cert-managerを使用したことがなく、Kubernetesを使用したこともない可能性があります。cert-managerが何を提供できるかを知りたいと考えています。別のチュートリアルでcert-managerについて聞いたことがあるかもしれません。cert-managerの代替手段とトレードオフを知りたい場合があります。自分のラップトップで評価できるように、cert-managerを迅速にインストールする必要があります。cert-managerの基本的な構成を学習する必要があります。次のステップを理解する必要があります。
継続的なユーザー
TLSで保護されたAPPをデプロイしたいプログラマー。cert-managerがクラスター管理者によってインストールされていることを知っています。既存のIssuerまたはClusterIssuerがあります。アプリケーションに適した証明書を作成する方法を知る必要があります。例：
- PostgreSQLデータベースの証明書を作成する
- Ingress/Gatewayの証明書を作成する。証明書が更新されない理由をデバッグする方法を知る必要があります。cert-managerの証明書と証明書要求のエラーメッセージを理解する必要があります。自分で修正できるエラーと、クラスター管理者の支援が必要なエラーを知る必要があります。
クラスター管理者
Kubernetesを知っています。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のコーディング標準とハウススタイルを学びます。cert-managerのテストを実行する方法を知る必要があります。
範囲
このプロジェクトの範囲は次のとおりです
- 3つのターゲットオーディエンスを特定し、説明します。
- これらのオーディエンスそれぞれについて、3つの主要なタスクを特定します。
- 既存のドキュメントを監査し、現在のドキュメントの摩擦ログを作成します。
- 摩擦ログをベースラインとして使用して、3つの主要なタスクの摩擦を最小限に抑えるようにドキュメントを再編成します。
- ドキュメントテスター（プロジェクトのボランティア）とより広いcert-managerコミュニティからのフィードバックを組み込みます。
- cert-managerチームと協力して、cert-manager.ioにドキュメントを公開します。
- オーディエンスとタスクを中心にコンテンツを構成する方法を説明する、Webサイトコントリビューター向けのドキュメントを作成します。
成功の測定
技術ライターが各オーディエンスの3つの主要なタスクを特定した後、タスクを達成するために必要なクリック数のベースラインを測定し、各タスクのクリック数を最小限に抑えることを目指します。
タイムライン
| 日付 | アクションアイテム |
|---|---|
| 5月 | オリエンテーション |
| 5月/6月 | 対象者とタスクを特定する |
| 5月/6月 | 監査と摩擦ログ |
| 6月 | タスクの再構築 |
| 6月/7月 | フィードバックの組み込み |
| 6月/7月 | cert-manager.ioに公開 |
| 7月 | Webサイトコントリビューター向けのガイダンスの記述を完了する |
| 7月 | プロジェクト完了 |
予算
| 予算項目 | 金額（$） | 累計（$） | 注 |
|---|---|---|---|
| 技術ライターによるcert-manager.ioドキュメントの監査と再構築 | 12,000 | 12,000 | |
| ボランティアの謝礼 | 1,500 | 13,500 | ボランティア3名 x 各500ドル |
| 合計 | 13,500 |
$12,000の金額について、経験豊富な技術ライター1名をパートタイム（たとえば、火曜日から金曜日まで半日、合計24日間、日給500ドルで3か月間）で雇用するのに十分であると想定しています。
"ボランティアの謝礼"は、プロジェクト期間中（5月1日から7月30日まで）に1ページの書き直しまたは一連のページの書き直しを行ったPRを1つ提出したコントリビューターに支給します。書き直しを開始する前に、ボランティアはSlack（Kubernetes Slack、チャネル#cert-manager-dev）またはGitHubのissueでどのページを書き直したいかを提案し、チームにこのページの書き直しが理にかなっているかどうかを確認します。少なくとも1つの肯定的な反応があれば、ボランティアは作業を開始できます。謝礼が有効になるには、PRをレビューしてマージする必要があります。
