本页面包含 Google 文档季接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- Cloud Native Computing Foundation (CNCF)
- 技术文档工程师：
- Syam Sundar K
- 项目名称：
- 更多更好的 Kubectl 示例
- 项目时长：
- 标准时长（3 个月）
Project description
此项目的动机是改进现有的 kubectl 备忘单和参考文档。
以下是此项目的最终目标： • 创建更多、更好的 kubectl 示例。 • 向 kubectl 备忘单添加了 kubectl 示例。 • 重构了 kubectl 文档，以最大限度地提高实用性。
目标 I - kubectl 示例：
将与 CLI 特别兴趣小组密切合作，了解 Kubernetes 用户最需要哪些示例，并记录这些示例。从改进备忘单上的现有 kubectl 命令，到向备忘单添加新命令，不一而足。
目标 II - 提高文档实用性：
为了提高文档的实用性，您可以执行以下操作：
• 消除新手难题 • 按特定顺序重新排列 kubectl 命令，以确保逻辑流程的连续性
通过更好的命令 / 用户情形解释消除初学者的困扰。这看似简单，但却会显著影响新手是否继续学习。举个例子，当我刚开始通过 kubectl 使用 Kubernetes 时，我并不确定 pod 和部署之间的区别。最初，我部署了一个使用 nodejs 编写的后端服务。几个小时后，我想要将其删除，因此尝试删除 Pod，但由于 Pod 具有自我修复特性，我们重新创建了 Pod。我对发生的情况感到困惑，想知道为什么系统会重新创建该项目，而不是将其删除。在网络上进行几次查找后，我发现删除 Pod 与删除部署并不相同。对于训练有素的眼睛来说，这可能很简单，但消除这类模糊性的清晰说明正是区分优秀文档和卓越文档的关键。
按特定顺序重新排列 kubectl 命令，以确保逻辑流程的连续性。如果您是像我这样坚信讲故事的人，您或许想知道，如何将讲故事的元素添加到包含终端命令列表的文档工作表中，我说这是可以做到的。我们学习的任何内容都有逻辑流程，也就是说，都有起点和终点。作为一款命令行工具，Kubectl 显然有一定的学习曲线，事实上，它的学习曲线与 Kubernetes 本身的学习曲线一致。由于几乎所有人都通过 kubectl 开始学习 Kubernetes（使用 Web 界面的用户除外），并且 kubectl 的学习曲线与 Kubernetes 的学习曲线紧密相关，因此只需更改这些命令的顺序并引入故事元素，即可显著改进文档。例如，在介绍资源后，可以使用现实世界的示例和插图来介绍 Pod 横向自动扩缩等功能。
目标 III - 改进文档易用性：
Kubernetes 网站最近迁移到 Docsy Hugo 是一件很棒的事，从文档角度来看，这是一个巨大的转变。虽然迁移已成功完成，但文档空间仍有很大的改进空间。
以下是我建议进行的一些更改
• 左侧窗格会自动滚动到主文档中当前处于活动状态的部分 - 这有助于跟踪当前、即将到来和过去的部分。 • 复制到剪贴板 - 某些命令可能很长，在处理这些类型的命令时，复制功能非常有用。 • 文档文件的内容格式设置 - 迁移后，一些页面中的内容的格式设置不正确。例如：kubectl 概览中的“Resource Type”部分。这会降低用户体验。
这些更改可以改善 kubernetes 网站上的用户体验，还可以提高用户的工作效率。