回顾 2019 年的文档工作

大家好！我是 Kubernetes 文档特别兴趣小组 (SIG Docs) 的联合主席之一。这篇博客文章是对 SIG Docs 2019 年工作的回顾。我们的贡献者去年做了出色的工作，我想强调他们的成功。

虽然本文回顾了 2019 年，但我的目标是展望 2020 年。我观察到 SIG Docs 的一些趋势——有些是好的，有些是令人担忧的。我想在这些挑战变得更加严峻之前提高可见性。

好的方面

2019 年 SIG Docs 有很多值得庆祝的事情。

Kubernetes 文档在年初有三个正在进行中的本地化。到年底，我们共有十个可用的本地化版本，其中四个（中文、法文、日文、韩文）相对完整。韩国团队因其在所有本地化工作中对 Git 最佳实践的贡献（韩国团队）以及帮助引导其他本地化工作（法国团队）而值得特别提及。

尽管这一年经历了重大转变，SIG Docs 提高了其评审速度，从 PR 开放到合并的平均评审时间仅略超过 24 小时。

问题分类在数量和速度上都有显著提高，这主要归功于 GitHub 用户 @sftim、@tengqm 和 @kbhawkey 的努力。

文档冲刺在 KubeCon 贡献者日仍然很有价值，它向新贡献者介绍了 Kubernetes 文档。

得益于发布负责人及其团队对操作手册的迭代改进，2019 年 Kubernetes 季度发布的文档组件有所改进。

网站流量在这一年有所增加。网站在 12 月结束时每月约有 600 万页面浏览量，高于 1 月份的约 500 万页面浏览量。kubernetes.io 网站在 10 月份有 85.1 万独立访客，创下历史新高。读者满意度 总体保持良好。

我们迎来了一位新的 SIG 主席：@jimangel，通用汽车的云架构师。Jim 曾是 docs 贡献者一年，期间他领导了 1.14 docs 发布，之后担任主席。

不太好的方面

虽然读者的满意度不错，但**大多数受访者表示对所有领域的过时内容感到不满意**：概念、任务、教程和参考。此外，读者还要求提供更多图表、高级概念内容和代码示例——这些都是技术写手擅长提供的。

SIG Docs 仍在研究如何最好地处理第三方内容。**kubernetes.io 上有太多供应商内容**，而且添加或拒绝第三方内容的指南仍然不明确。到目前为止，讨论非常激烈，包括要求更多协作投入的强烈反对——这有力地提醒我们，Kubernetes 始终是一项共同努力。

我们在 18 个月内正经历第三次主席交接。每一次主席交接都健康且友好，但在短时间内如此频繁的轮换仍然是很大的挑战。主持任何开源项目都很困难，但 SIG Docs 尤其如此。SIG Docs 的主席职责需要在多个领域进行陡峭的学习曲线：文档（包括书面和从规范生成的文档）、信息架构、专门的贡献路径（例如，本地化）、如何运行发布周期、网站开发、CI/CD、社区管理等等。这是一个需要多人才能成功运作而不会让人筋疲力尽的角色。培训接班人需要大量时间。

也许在“不太好的方面”中最紧迫的是，SIG Docs 目前只有一名技术写作者全职致力于 Kubernetes 文档。这会对 Kubernetes 文档产生影响：有些是显而易见的，有些则不那么明显。

Kubernetes 文档人员不足的影响

今天的我：pic.twitter.com/cDpHOWEsjf

— Benjamin Elder (@BenTheElder) 2020 年 1 月 10 日

如果 Kubernetes 在 2020 年没有更多专门负责文档的技术撰稿人，我认为最有可能出现以下情况。

但首先，免责声明

我的一些预测几乎肯定是错误的。任何错误都由我个人承担。

话虽如此...

2020 年的影响

当前的职能水平无法自我维持。即使有强大的操作手册，发布周期仍然需要每个周期至少一名（通常是两名）主席的专家支持。毫无疑问，每个版本都会以新的、意想不到的方式出现问题，需要熟悉和专业知识才能诊断和解决。随着主席的不断轮换——明确地说，定期过渡是健康项目的一部分——我们面临着由于缺乏足够的专业深度和雇主支持而带来的风险。

奇怪的是，人员配置的一个挑战是文档看起来足够好。根据网站分析和调查回复，读者对文档的质量感到满意。当人们访问网站时，他们通常能找到所需的内容，并表现出满意的访客行为。

危险在于，这种情况会随着时间的推移而改变：缓慢地，偶尔出现功能丧失，起初令人烦恼，然后变得越来越关键。如果没有足够的人员配备，时间越长，修复就越困难、成本越高。

我怀疑这是真的，因为即使在读者满意度尚可的情况下，我们现在面临的挑战也已经很难解决。API 参考生成复杂且脆弱；网站 UI 过时；我们最持续的需求是更多教程、高级概念、图表和代码示例，所有这些都需要持续的、专门的时间来创建。

发布支持依然强劲。

发布团队继续保持着一个良好的习惯，即为每个后续团队提供比前一个版本更好的支持。这主要体现在对文档发布操作手册的迭代改进上，从而产生更好的文档并减少知识孤岛。

内容陈旧加速。

随着功能的更改或废弃，概念性内容变得不那么准确或不相关。教程内容也因此而退化。

内容结构也将退化：概念、任务和教程的分类是旧有的分类，可能无法最好地满足当前读者的需求，更不用说未来的读者了。

对于读者和贡献者来说，冗余内容都会积累。如果没有干预，参考文档将变得越来越脆弱。

关键知识正在消失。

正如我之前提到的，SIG Docs 具有广泛的功能，其中一些具有陡峭的学习曲线。随着贡献者角色或工作的变化，他们的专业知识和可用性将减少或归零。具有特定知识的贡献者可能无法提供咨询，从而暴露文档功能中的关键漏洞。具体示例包括引用生成和主席领导。

信息量很大

很难在 SIG Docs 工作对社区和用户的重要性、它给我个人带来的乐趣以及如果不进行重大改变就会产生（最终）负面影响的事实之间取得平衡。SIG Docs 绝非垂死挣扎；它是一个充满活力的社区，拥有积极的贡献者，做着很酷的事情。它也是一个存在一些关键知识和能力短缺的社区，只能通过经过培训、有偿的专职文档人员来解决。

社区能为健康的文档做些什么

聘请专门负责 Kubernetes 文档的技术撰稿人。支持高级内容创建，而不仅仅是发布文档和增量功能更新。

谢谢，祝您 2020 年快乐。

• ←上一篇
• 下一篇→