本页面包含有关 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 与 Deployment 之间的区别。最初，我部署了一项用 nodejs 编写的后端服务。几小时后，我想将其移除，因此我尝试了删除 Pod，但由于 Pod 的自我修复特性，我们再次创建了它们。我对当时的情况感到困惑，想知道为什么对象会重新创建，却没有被删除。在网络上进行几次查找后，我发现删除 Pod 与删除部署是不一样的。对于专业的人来说，这可能看上去很简单，但通过清晰明确的说明可以消除这些类型的歧义，这是优秀文档与优秀文档的区别所在。
按特定顺序重新排列 kubectl 命令，以确保逻辑流的连续性。如果您像我一样非常喜欢讲故事，您可能会好奇，如何将讲故事元素放入包含一系列终端命令的文档工作表中，我觉得这是可以实现的。我们学到的任何东西总都有一个逻辑流，一个起点和一个终点（如果您愿意的话）。Kubectl 作为命令行工具，显然有一个学习曲线，事实上，它的学习曲线与 Kubernetes 本身的学习曲线不谋而合。由于几乎所有人都通过 kubectl 开始使用 kubernetes（使用网页界面的人除外），并且它的学习曲线与 Kubernetes 的学习曲线紧密相关，因此只需更改这些命令的顺序并引入讲故事元素，即可显著改善文档。举个例子，在使用实际示例和插图说明资源之后，可以解释 Pod 横向自动扩缩等功能。
目标 III - 文档易用性改进：
最近将 Kubernetes 网站迁移到了 Docsy Hugo，这太棒了，这是从文档角度而言的巨大转变。虽然迁移已成功完成，但在文档空间方面仍有许多改进的空间。
下面是我建议做出的一些更改
• 左侧窗格会自动滚动到主文档中当前进行的部分 - 这对于跟踪当前、即将推出和以往的部分很有帮助。 • 复制到剪贴板 - 某些命令可能比较长，在处理这些类型的命令时，复制功能会很有用。 • 文档文件的内容格式设置 - 迁移后，一些页面内容的格式设置不正确。例如：kubectl 概览中的“Resource Type”部分。这会降低用户体验。
这些变化可以改善 Kubernetes 网站上的用户体验，也可以提高用户的工作效率。