Kubernetes 文档最终用户调研

Author: Aimee Ukasick and SIG Docs

9月，SIG Docs 进行了第一次关于 Kubernetes 文档的用户调研。我们要感谢 CNCF 的 Kim McMahon 帮助我们创建调查并获取结果。

主要收获

受访者希望能在概念、任务和参考部分得到更多示例代码、更详细的内容和更多图表。

74% 的受访者希望教程部分包含高级内容。

69.70% 的受访者认为 Kubernetes 文档是他们首要寻找关于 Kubernetes 资料的地方。

调查方法和受访者

我们用英语进行了调查。由于时间限制，调查的有效期只有 4 天。 我们在 Kubernetes 邮件列表、Kubernetes Slack 频道、Twitter、Kube Weekly 上发布了我们的调查问卷。 这份调查有 23 个问题， 受访者平均用 4 分钟完成这个调查。

关于受访者的简要情况

• 48.48% 是经验丰富的 Kubernetes 用户，26.26% 是专家，25.25% 是初学者
• 57.58% 的人同时使用 Kubernetes 作为管理员和开发人员
• 64.65% 的人使用 Kubernetes 文档超过 12 个月
• 95.96% 的人阅读英文文档

问题和回答要点

人们为什么访问 Kubernetes 文档

大多数受访者表示，他们访问文档是为了了解概念。

这与我们在 Google Analytics 上看到的略有不同：在今年浏览量最多的10个页面中，第一是在参考部分的 kubectl 的备忘单，其次是概念部分的页面。

对文档的满意程度

我们要求受访者从概念、任务、参考和教程部分记录他们对细节的满意度：

• 概念：47.96% 中等满意
• 任务：50.54% 中等满意
• 参考：40.86% 非常满意
• 教程：47.25% 中等满意

SIG Docs 如何改进文档的各个部分

我们询问如何改进每个部分，为受访者提供可选答案以及文本输入框。绝大多数人想要更多 示例代码、更详细的内容、更多图表和更高级的教程：

- 就个人而言，希望看到更多的类比，以帮助进一步理解。
- 如果代码的相应部分也能解释一下就好了
- 通过扩展概念把它们融合在一起 - 它们现在宛如在一桶水内朝各个方向游动的一条条鳗鱼。
- 更多的图表，更多的示例代码

受访者使用“其他”文本框记录引发阻碍的区域：

- 使概念保持最新和准确
- 保持任务主题的最新性和准确性。亲身试验。
- 彻底检查示例。很多时候显示的命令输出不是实际情况。
- 我从来都不知道如何导航或解释参考部分
- 使教程保持最新，或将其删除

SIG Docs 如何全面改进文档

我们询问受访者如何从整体上改进 Kubernetes 文档。一些人抓住这次机会告诉我们我们正在做一个很棒的 工作：

- 对我而言，这是我见过的文档最好的开源项目。
- 继续努力！
- 我觉得文档很好。
- 你们做得真好。真的。

其它受访者提供关于内容的反馈：

-  ...但既然我们谈论的是文档，多多益善。更多的高级配置示例对我来说将是最好的选择。比如每个配置主题的用例页面，
从初学者到高级示例场景。像这样的东西真的是令人惊叹......
- 更深入的例子和用例将是很好的。我经常感觉 Kubernetes 文档只是触及了一个主题的表面，这可能对新用户很好，
但是它没有让更有经验的用户获取多少关于如何实现某些东西的“官方”指导。
- 资源节（特别是 secrets）希望有更多类似于产品的示例或指向类似产品的示例的链接
- 如果能像很多其它技术项目那样有非常清晰的“快速启动” 逐步教学完成搭建就更好了。现有的快速入门内容屈指可数，
也没有统一的指南。结果是信息泛滥。

少数受访者提供的技术建议：

- 使用 ReactJS 或者 Angular component 使表的列可排序和可筛选。
- 对于大多数人来说，我认为用 Hugo - 一个静态站点生成系统 - 创建文档是不合适的。有更好的系统来记录大型软件项目。
具体来说，我希望看到 k8s 切换到 Sphinx 来获取文档。Sphinx 有一个很好的内置搜索。如果你了解 markdown，学习起来也很容易。
Sphinx 被其他项目广泛采用（例如，在 readthedocs.io、linux kernel、docs.python.org 等等）。

总体而言，受访者提供了建设性的批评，其关注点是高级用例以及更深入的示例、指南和演练。

哪里可以看到更多

调查结果摘要、图表和原始数据可在 kubernetes/community sig-docs survey 目录下。

• ← 上一页
下一页 →