From 0c36d6b6b54f3102df9958f6846858c62f817b19 Mon Sep 17 00:00:00 2001 From: Sophy417 <53026875+Sophy417@users.noreply.github.com> Date: Wed, 9 Dec 2020 14:56:49 +0800 Subject: [PATCH] Create 2019-10-29-2019-sig-docs-survey.md --- .../_posts/2019-10-29-2019-sig-docs-survey.md | 283 ++++++++++++++++++ 1 file changed, 283 insertions(+) create mode 100644 content/zh/blog/_posts/2019-10-29-2019-sig-docs-survey.md diff --git a/content/zh/blog/_posts/2019-10-29-2019-sig-docs-survey.md b/content/zh/blog/_posts/2019-10-29-2019-sig-docs-survey.md new file mode 100644 index 0000000000..3fc5bfa360 --- /dev/null +++ b/content/zh/blog/_posts/2019-10-29-2019-sig-docs-survey.md @@ -0,0 +1,283 @@ +--- +layout: blog +title: "Kubernetes 文献调查" +date: 2019-10-29 +slug: kubernetes-documentation-end-user-survey +--- + + +**Author:** [Aimee Ukasick](https://www.linkedin.com/in/aimee-ukasick/) and SIG Docs + + +9月,SIG Docs 进行了第一次关于 [Kubernetes 调查文件](https://kubernetes.io/docs/) 。我们要感谢 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 文档 + + +大多数受访者表示,他们访问文档是为了了解概念。 + +{{< figure + src="/images/blog/2019-sig-docs-survey/Q9-k8s-docs-use.png" + alt="受访者为什么访问 Kubernetes 文档" +>}} + + +这与我们在 Google Analytics 上看到的略有不同:在今年浏览量最多的10个页面中,第一是在参考部分的 kubectl +的备忘单,其次是概念部分的页面。 + + +## 对文档的满意程度 + + +我们要求受访者从概念、任务、参考和教程部分记录他们对细节的满意度: + + +- 概念:47.96% 中等满意 +- 任务:50.54% 中等满意 +- 参考:40.86% 非常满意 +- 教程:47.25% 中等满意 + + +## SIG Docs 如何改进文档的各个部分 + + +我们询问如何改进每个部分,为受访者提供可选答案以及文本输入框。绝大多数人想要更多 +示例代码、更详细的内容、更多图表和更高级的教程: + + +```text +- 就个人而言,希望看到更多的类比,以帮助进一步理解。 +- 如果代码的相应部分也能解释一下就好了 +- 通过扩展概念把它们融合在一起 - 它们现在宛如在一桶水内朝各个方向游动的一条条鳗鱼。 +- 更多的图表,更多的示例代码 +``` + + +受访者使用“其他”文本框记录引发阻碍的区域: + + +```text +- 使概念保持最新和准确 +- 保持任务主题的最新性和准确性。亲身试验。 +- 彻底检查示例。很多时候显示的命令输出不是实际情况。 +- 我从来都不知道如何导航或解释参考部分 +- 使教程保持最新,或将其删除 +``` + + +## SIG Docs 如何全面改进文档 + + +我们询问受访者如何从整体上改进 Kubernetes 文档。一些人抓住这次机会告诉我们我们正在做一个很棒的 +工作: + + +```text +- 对我而言,这是我见过的文档最好的开源项目。 +- 继续努力! +- 我觉得文件很好。 +- 你们做得真好。真的。 +``` + + +其它受访者提供关于内容的反馈: + + +```text +- ...但既然我们谈论的是文档,多多益善。更多的高级配置示例对我来说将是最好的选择。比如每个配置主题的用例页面,从初学者到高级示例场景。像这样的东西真的是令人惊叹...... + + +- 更深入的例子和用例将是很好的。我经常感觉 Kubernetes 文档只是触及了一个主题的表面,这可能对新用户很好,但是它没有让更有经验的用户获取多少关于如何实现某些东西的“官方”指导。 + + +- 资源节(特别是 secrets)希望有更多类似于产品的示例或指向类似产品的示例的链接 + + +- 如果能像很多其它技术项目那样有非常清晰的“快速启动” 逐步教学完成搭建就更好了。 + 现有的快速入门内容屈指可数,也没有统一的指南。结果是信息泛滥。 +``` + + +少数受访者提供的技术建议: +```text +- 使用 ReactJS 或者 Angular component 使表的列可排序和可筛选。 + + +- 对于大多数人来说,我认为用 Hugo - 一个静态站点生成系统 - 创建文档是不合适的。有更好的系统来记录大型软件项目。 + + +具体来说,我希望看到 k8s 切换到 Sphinx 来获取文档。Sphinx 有一个很好的内置搜索。 +如果你了解 markdown,学习起来也很容易。 +Sphinx 被其他项目广泛采用(例如,在 readthedocs.io、linux kernel、docs.python.org 等等)。 +``` + + +总体而言,受访者提供了建设性的批评,其关注点是高级用例以及更深入的示例、指南和演练。 + + +# 哪里可以看到更多 + + +调查结果摘要、图表和原始数据可在 `kubernetes/community` sig-docs +[survey](https://github.com/kubernetes/community/tree/master/sig-docs/survey) +目录下。