Kubernetes文档调查

作者: 艾米·乌卡西克(Aimee Ukasick) 和SIG文档

九月份,SIG Docs进行了有关 Kubernetes documentation。我们要感谢CNCF的Kim McMahon帮助我们创建了调查并访问了结果。

重要要点

受访者想要更多示例代码,更多详细内容以及更多内容 概念,任务和参考部分中的图表。

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

69.70%的人说Kubernetes文档是他们寻找的第一位 有关Kubernetes的信息。

调查方法和受访者

我们用英语进行了调查。该调查仅可使用4天 受时间限制。我们在Kubernetes邮件列表中宣布了这项调查, Kubernetes Slack频道,Twitter和Kube Weekly。有23 问题,受访者平均花费4分钟来完成调查。

有关受访者的事实:

  • 经验丰富的Kubernetes用户为48.48%,专家为26.26%,初学者为25.25%
  • 57.58%在管理员和开发人员角色中使用Kubernetes
  • 64.65%的用户使用Kubernetes文档已有12个月以上
  • 95.96%阅读英语文档

问题与回应重点

人们为什么要访问Kubernetes文档

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

为什么受访者访问Kubernetes文档

这仅与我们在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 文件资料 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 文件资料 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 文件资料. 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).

总体而言,受访者提出了建设性批评,重点放在 高级用例以及更深入的示例,指南和演练。

在哪里可以看到更多

Survey results 概要, charts, and raw data are available in kubernetes/community sig-docs 调查 目录。