本文发布已超过一年。较旧的文章可能包含过时的内容。请检查页面中的信息自发布以来是否已失效。

回顾 2019 年文档工作

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

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

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

好的方面

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

Kubernetes 文档在年初有三个正在进行的本地化项目。到年底，我们共有十个可用的本地化版本，其中四个（中文、法文、日文、韩文）已相当完善。韩文团队和法文团队值得特别提及，他们分别为所有本地化项目贡献了 Git 最佳实践（韩文团队）和帮助启动其他本地化项目（法文团队）。

尽管在这一年里经历了显著的过渡，SIG Docs 提高了审查速度，PR 从打开到合并的中位数审查时间仅略多于 24 小时。

Issue 分类（triage）在数量和速度上都有了显著改进，这主要归功于 GitHub 用户 @sftim、@tengqm 和 @kbhawkey 的努力。

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

感谢发布负责人及其团队迭代改进的 playbook，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 年的影响

当前的功能水平无法自我维持。即使有完善的 playbook，每个发布周期仍然需要至少一名（通常是两名）主席提供专家支持。每次发布都会以新的、意想不到的方式出现问题，并且需要熟悉和专业知识来诊断和解决。随着主席的不断轮换——需要说明的是，定期过渡是健康项目的一部分——我们积累了因缺乏足够的专业深度和雇主支持而带来的风险。

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

危险在于这种情况会随时间改变：功能会缓慢地偶尔丢失，一开始令人烦恼，然后变得越来越关键。没有足够的人员配备，时间拖得越久，修复问题就越困难、成本越高。

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

发布支持依然强劲。

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

陈旧内容加速增加。

随着功能变化或弃用，概念内容变得不够准确或不再相关。教程内容也因同样的原因退化。

内容结构也会退化：概念、任务和教程这些类别是遗留类别，可能不再最适合当前读者的需求，更不用说未来的读者了。

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

关键知识正在流失。

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

信息量很大

很难在 SIG Docs 工作对社区和用户的重要性、它给我个人带来的快乐以及如果不改变现状最终会带来重大负面影响这一事实之间找到平衡。SIG Docs 绝不是濒临消亡；它是一个充满活力的社区，有积极的贡献者在做很酷的事情。但它也是一个存在一些关键知识和能力短缺的社区，这些问题只能通过训练有素、有报酬且专注于文档工作的人员来解决。

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

雇佣专注于 Kubernetes 文档的技术文档作者。支持高级内容创作，而不仅仅是发布文档和增量功能更新。

感谢，祝 2020 年快乐。