改进 cert-manager 网站的导航和结构
项目更新
2022 年 9 月 7 日：Webhook 调试指南
在 Google Season of Docs 项目开始时，我们为常见用户任务（如调试“connect: connection refused”错误）构建了摩擦日志。 此任务的摩擦日志（在GSoD 工作文档中可见）旨在作为参考点，以查看我们旨在带来的改进是否会产生影响。
摩擦日志显示了持续的模式：用户在 Google 上搜索错误，对没有解决方案的 GitHub 问题感到困惑，然后点击 Google 结果中的第二个链接，但没有多少运气。 我们意识到我们可以做出的一个改进是在 FAQ 页面“排查 Webhook 问题”中添加一个链接。 我们发现此 FAQ 页面有两个问题
- 任何人都找不到它，因为页面中没有列出错误消息，这意味着 Google 不会在搜索结果中显示该页面。
- 许多错误消息未在页面中列出。
我们开始重写此页面，目标是使其以错误为中心，这意味着用户只需查找其特定的错误并开始调试它。 我们称之为“cert-manager Webhook Pod 的终极调试指南”，它可以在这里找到。
2022 年 8 月 12 日：改进了导航菜单的布局
在 >=1280px 的显示器上，左侧菜单太窄，无法清晰地显示嵌套的菜单项。 在较小的显示器上，响应式 CSS实际上使菜单更大。 因此，我们在 >=1280px 的显示器上将其宽度扩展了一列，并减少了内容的宽度一列以进行补偿。 这使得菜单在笔记本电脑和台式机屏幕上更容易阅读。
我们修复了具有子菜单的菜单项与没有子菜单的菜单项之间的垂直间距不一致问题。
最后，我们将版本选择器移到侧边栏的底部，以避免分散读者的注意力。
2022 年 8 月 3 日：cert-manager.io 文档调查现已结束
感谢所有参与我们文档调查的人。 我们将使用这些结果来优先考虑网站中需要重组和重写的部分。 在本季 Docs 结束之前，我们将从所有答复者中随机抽取一位获奖者，并与您联系以告知您的奖品。
2022 年 7 月 18 日：cert-manager.io 文档调查
我们创建了一个简短的调查，以帮助我们确定 cert-manager.io 文档的最高优先级。
- 我们希望确定最有用的文档，这样我们就不需要更改那些已经运作良好的内容。
- 我们想知道哪些文档没有用，以便我们可以改进。
- 我们希望从新用户和经验丰富的用户那里了解他们如何以及多久使用一次文档。
- 我们还想了解您在 cert-manager.io 网站之外的其他地方在哪里找到了有关 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 网站编写一些官方指南，演示如何快速安装 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（UTC 时间 14:00）在 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 的信息。 这些信息是存在的，但分散在多个页面上，而且通常不在显而易见的位置。
例如，一个寻找关于如何使用证书资源的指南的用户，在意识到“证书”页面存在两次（一次在“使用”部分，一次在“概念”部分）时，可能会感到无助。
（注意：此屏幕截图来自我们旧的网站设计，但文本和布局基本相同）
我们希望有一位技术作家
- 帮助我们确定我们的目标受众，以及
- 确定每个受众的关键任务，以及
- 根据此重新构建 cert-manager.io 网站。
例如，我们讨论了以下受众和任务：初学者、集群管理员、用户、集成者、新贡献者，并且这些人会对不同的任务感兴趣。我们希望他们能够快速轻松地找到他们需要的信息。
通过使每个群体更容易找到他们需要的信息，我们旨在减少支持查询的数量。
受众
新用户
从未使用过 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。可能想要让 cert-manager 与其他集群范围的系统（如 Istio 或 Knative）协同工作。
集成者
可能想要允许 cert-manager 用户使用自定义证书服务。可能想要将 cert-manager 与 DNS API 集成以用于 ACME DNS01。可能想要依赖 cert-manager 来管理更高级系统（如 Istio 或 Knative）的 TLS 证书。需要学习如何为 cert-manager 编写插件/扩展。需要指向插件和扩展的最先进示例的链接。
新贡献者
想要报告 cert-manager 中的错误。想要修复 cert-manager 中的错误。想要为 cert-manager 建议功能。想要为 cert-manager 实现功能。需要学习如何浏览 cert-manager 代码。了解 cert-manager 的编码标准和风格。需要了解如何运行 cert-manager 的测试。
范围
本项目范围如下
- 确定并描述三个目标受众。
- 为每个受众确定三个关键的顶级任务。
- 审计现有文档并创建当前文档的摩擦日志。
- 以摩擦日志为基准，重新组织文档以最大程度地减少完成三个顶级任务的摩擦。
- 纳入文档测试人员（项目志愿者）和更广泛的 cert-manager 社区的反馈。
- 与 cert-manager 团队合作，在 cert-manager.io 上发布文档。
- 为网站贡献者创建文档，解释我们如何围绕受众和任务构建内容。
衡量成功
在技术作家帮助我们确定每个受众的 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 需要被审查和合并。
