本文发表于一年多前。旧文章可能包含过时内容。请检查页面中的信息自发布以来是否已变得不正确。

Kubernetes 文档调查

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 文档

大多数受访者表示,他们为了概念而访问文档。

Why respondents access the Kubernetes documentation

这与我们在 Google Analytics 中看到的结果略有不同:今年浏览量前 10 的页面中,排名第一的是参考部分中的 kubectl 备忘单,其次绝大多数是概念部分的页面。

对文档的满意度

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

  • 概念:47.96% 比较满意
  • 任务:50.54% 比较满意
  • 参考:40.86% 非常满意
  • 教程:47.25% 比较满意

SIG Docs 如何改进每个文档部分

我们询问了如何改进每个部分,为受访者提供了可选择的答案以及文本字段。绝大多数受访者希望获得更多示例代码、更详细的内容、更多图表和高级教程。

- Personally, would like to see more analogies to help further understanding.
- Would be great if corresponding sections of code were explained too
- Expand on the concepts to bring them together - they're a bucket of separate eels moving in different directions right now
- More diagrams, and more example code

受访者使用“其他”文本框记录了导致挫折的领域。

- Keep concepts up to date and accurate
- Keep task topics up to date and accurate. Human testing.
- Overhaul the examples. Many times the output of commands shown is not actual.
- I've never understood how to navigate or interpret the reference section
- Keep the tutorials up to date, or remove them

SIG Docs 如何整体改进文档

我们询问了如何整体改进 Kubernetes 文档。一些受访者借此机会告诉我们做得很好。

- For me, it is the best documented open source project.
- Keep going!
- I find the documentation to be excellent.
- You [are] doing a great job. For real.

其他受访者提供了关于内容的反馈。

-  ...But since we're talking about docs, more is always better. More
advanced configuration examples would be, to me, the way to go. Like a Use Case page for each
configuration topic with beginner to advanced example scenarios. Something like that would be
awesome....
- More in-depth examples and use cases would be great. I often feel that the Kubernetes
documentation scratches the surface of a topic, which might be great for new users, but it leaves
more experienced users without much "official" guidance on how to implement certain things.
- More production like examples in the resource sections (notably secrets) or links to production like
examples
- It would be great to see a very clear "Quick Start" A->Z up and running like many other tech
projects. There are a handful of almost-quick-starts, but no single guidance. The result is
information overkill.

少数受访者提供了技术建议。

- Make table columns sortable and filterable using a ReactJS or Angular component.
- For most, I think creating documentation with Hugo - a system for static site generation - is not
appropriate. There are better systems for documenting large software project. Specifically, I would
like to see k8s switch to Sphinx for documentation. It has an excellent built-in search, it is easy to
learn if you know markdown, it is widely adopted by other projects (e.g. every software project in
readthedocs.io, linux kernel, docs.python.org etc).

总的来说,受访者提供了建设性的批评,主要集中在需要高级用例以及更深入的示例、指南和演练。

在哪里可以查看更多信息

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