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

回顾 2019 年的文档

作者：Zach Corleissen (云原生计算基金会) |

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

尽管我在这篇文章中回顾了 2019 年，但我的目标是指向 2020 年。我观察到 SIG Docs 的一些趋势——有些是好的，有些是令人担忧的。我想在这些挑战加剧之前提高可见性。

好的方面

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

Kubernetes 文档在年初开始了三项本地化工作。到年底，我们最终提供了十个本地化版本，其中四个（中文、法语、日语、韩语）相当完整。韩语和法语团队值得特别提及，他们为所有本地化版本（韩语团队）的 Git 最佳实践做出了贡献，并帮助引导了其他本地化版本（法语团队）。

尽管一年中经历了重大转变，SIG Docs 提高了审查速度，从 PR 打开到合并的中位审查时间仅为 24 小时多一点。

问题分类的量和速度都得到了显着提高，这主要归功于 GitHub 用户 @sftim、@tengqm 和 @kbhawkey 的努力。

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

得益于发布负责人及其团队的迭代式剧本改进，Kubernetes 每季度发布的文档组件在 2019 年得到了改进。

网站流量全年都在增加。该网站在 12 月底的每月页面浏览量约为 600 万次，高于 1 月份的约 500 万次。kubernetes.io 网站在 10 月份的网站访问量为 85.1 万，创历史新高。读者满意度仍然总体满意。

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

不太好的方面

虽然读者满意度还不错，但大多数受访者表示对每个领域（概念、任务、教程和参考）中过时的内容不满意。此外，读者还要求提供更多的图表、高级概念内容和代码示例，而这些都是技术作家擅长提供的。

SIG Docs 继续研究如何最好地处理第三方内容。kubernetes.io 上有太多供应商内容，并且添加或拒绝第三方内容的指南仍然不明确。到目前为止的讨论非常有力，包括要求更多协作投入的抵制——这有力地提醒我们，Kubernetes 在各方面都是一项社区努力。

我们正处于 18 个月内的第三次主席过渡期。每次主席过渡都是健康和友好的，但这仍然是在短时间内的大量人员流动。主持任何开源项目都很困难，但 SIG Docs 尤其如此。SIG Docs 的主席职位需要在多个领域具有陡峭的学习曲线：文档（书面和从规范生成）、信息架构、专门的贡献路径（例如，本地化）、如何运行发布周期、网站开发、CI/CD、社区管理等等。这是一个需要多人才能成功运作的角色，而不会让人精疲力竭。培训替代者非常耗时。

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

人员不足对 Kubernetes 文档的影响

如果 Kubernetes 在 2020 年继续没有更多致力于文档的技术作家，那么我看到最有可能出现的情况如下。

但首先，免责声明

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

话虽如此...

2020 年的影响

目前的功能水平并非自我维持。即使有一个强大的剧本，发布周期仍然需要在每个周期中至少一位（通常是两位）主席的专家支持。毫无例外，每次发布都会以新的和意想不到的方式中断，并且需要熟悉和专业知识来诊断和解决。随着主席继续轮换——并且要明确的是，定期过渡是健康项目的一部分——我们会承担与缺乏足够专业深度和雇主支持的人员池相关的风险。

奇怪的是，人员配备的挑战之一是文档看起来足够好。根据网站分析和调查反馈，读者对文档的质量感到满意。当人们访问该网站时，他们通常会找到他们需要的东西，并且表现得像满意的访问者。

危险在于，这种情况会随着时间的推移而改变：缓慢地，偶尔会出现功能丢失，起初令人烦恼，然后变得越来越关键。没有充足人员配备的时间越长，修复工作就越困难和昂贵。

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

发布支持仍然强劲。

发布团队继续保持着良好的习惯，使每个连续的团队都能获得比上一次发布更好的支持。这主要采取迭代改进文档发布剧本的形式，从而产生更好的文档并减少孤立的知识。

过时加速。

随着功能更改或弃用，概念内容变得不太准确或相关。教程内容也因同样的原因而降级。

内容结构也会降级：概念、任务和教程的类别是旧的类别，可能并不最适合当前读者的需求，更不用说未来的读者了。

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

关键知识消失。

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

这需要考虑很多

在 SIG Docs 的工作对社区和用户的重要性、它给我个人带来的快乐以及如果不进行重大负面影响（最终）就无法保持现状的事实之间取得平衡是很困难的。SIG Docs 绝不是正在消亡；它是一个充满活力的社区，活跃的贡献者正在做很酷的事情。它也是一个社区，在一些关键知识和能力方面存在不足，而这些不足只能通过训练有素、有报酬的、专门从事文档工作的人员来解决。

社区可以为健康文档做些什么

聘请专门从事 Kubernetes 文档的技术作家。支持高级内容创建，而不仅仅是发布文档和增量功能更新。

谢谢，2020 年快乐。