本文已发表一年多。较早的文章可能包含过时内容。请检查页面信息自发布以来是否已发生变化。

深入理解文档

作者 Aimee Ukasick (独立贡献者) |
grok: to understand profoundly and intuitively

定义来自 Merriam Webster 在线词典

引言 - 新晋 SIG Docs 贡献者的观察

我于 2019 年 8 月开始为 SIG Docs 社区贡献力量。有时，我感觉自己像是身处异乡的陌生人，正在适应一个新社区：调查社区组织、理解贡献者群体、学习新知识并吸收新术语。我既是一名观察者，也是一名贡献者。

观察 01: 阅读 贡献 页面！

我曾为 OpenStack、OPNFV 和 Acumos 贡献过代码和文档，所以我以为为 Kubernetes 文档做贡献也会一样。我错了。我本应彻底地阅读 为 Kubernetes 文档做贡献 页面，而不是草草浏览。

我非常熟悉 git/gerrit 工作流程。使用这些工具，贡献者会克隆 master 仓库，然后创建本地分支。Kubernetes 使用一种不同的方法，称为 Fork and Pull。每个贡献者 fork master 仓库，然后将工作推送到他们的 fork，之后再创建拉取请求。我按照开始贡献页面 提交拉取请求 部分的说明创建了一个简单的拉取请求（PR）。该部分描述了如何使用 GitHub UI 进行文档更改。我了解到这种方法对于只需要一个提交来修复的更改来说是没问题的。但是，当你必须对你的 PR 进行额外更新时，这种方法就变得复杂了。使用 GitHub UI 进行的每次更改，GitHub 都会创建一个新的提交。Kubernetes GitHub 组织要求压平提交（squashing commits）。开始贡献页面没有提及压平提交，所以我查阅了 GitHub 和 git 文档。我无法使用 GitHub UI 压平我的提交。我不得不先在本地 git fetch 和 git checkout 我的拉取请求，然后使用命令行压平提交，再推送我的更改。如果开始贡献页面提及了压平提交，我就会从本地克隆仓库开始工作，而不是使用 GitHub UI。

观察 02: 主动寻求帮助并联系他人

在处理我的第一个 PR 时，我对于从本地克隆仓库工作以及如何使我的 fork 与 upstream master 保持同步有很多疑问。我选择了上网搜索，而不是在 Kubernetes Slack 的 #sig-docs 频道提问。我使用了错误的流程来更新我的 fork，因此我不得不对我的 PR 进行 git rebase，这根本就不顺利。结果是，我关闭了那些 PR，并提交了新的。当我在 #sig-docs 频道寻求帮助时，贡献者们提供了有用的链接、我的本地 git 配置文件应该是什么样子，以及需要运行的确切 git 命令集。贡献者们使用的工作流程与进阶贡献页面定义的不同。如果我当时询问应该使用哪种 GitHub 工作流程，我就会节省大量时间。社区知识文档化得越多，新贡献者就能越快地提高效率。

观察 03: 不要让冲突的信息毁了你的一天

Kubernetes 社区有一个针对代码的贡献者指南，以及另一个针对文档的贡献者指南。这些指南在同一主题上包含冲突的信息。例如，SIG Docs 的 GitHub 工作流程建议基于 upstream/master 创建本地分支。Kubernetes 社区贡献者指南则提倡从 upstream 更新你的 fork，然后基于你的 fork 创建本地分支。新贡献者应该遵循哪个流程？这两个流程可以互换吗？提问关于冲突信息的最佳地点是 #sig-docs 或 #sig-contribex 频道。我在 #sig-contribex 频道询问了关于 GitHub 工作流程的澄清。@cblecker 提供了非常详细的回复，我用这些信息更新了进阶贡献页面。

观察 04: 信息可能分散各处

对于大型开源项目来说，信息分散在不同的仓库中或在仓库之间重复是很常见的。有时，小组各自为政（work in silos），信息不共享。另一些时候，有人离开去参与不同的项目，却没有传递专业知识。文档存在空白，并且可能由于优先级更高的事情而永远无法得到弥补。因此，新贡献者可能难以找到基本信息，例如会议详情。

参加 SIG Docs 会议是参与其中的绝佳方式。然而，人们一直难以找到会议 URL。大多数新贡献者会在 #sig-docs 频道提问，但我决定在文档中查找会议信息。这需要在多个页面上点击数次。有多少新贡献者因为找不到会议详情而错过了会议？

观察 05: 耐心是一种美德

对于较大的 PR，贡献者可能需要等待数天才能收到反馈。从提交到最终批准的过程可能需要数周而不是数天。这有两个原因：1) 大多数评审者在 SIG Docs 上是兼职工作；2) 评审者希望提供有意义的评审。“敷衍评审”（Drive-by reviewing）在 SIG Docs 不存在！评审者会检查以下内容：

  • 提交消息和 PR 描述是否充分描述了更改？

  • PR 是否遵循了风格和内容指南中的规定？

    • 总体而言，语法和标点是否正确？
    • 内容是否清晰、简洁，并且适合非母语使用者？
    • 内容在风格上是否与其他文档一致？
    • 内容的逻辑流程是否合理？
    • 可以做任何更改来使内容更好吗，例如使用 Hugo shortcode？
    • 内容是否正确渲染？

  • 内容技术上是否正确？

有时，评审过程让我感到防御、恼火和沮丧。我确信其他贡献者也有同感。贡献者们需要耐心！编写优秀文档是一个迭代的过程。评审者严格审查 PR 是因为他们想维护文档的高质量水平，而不是想惹恼贡献者！

观察 06: 字字珠玑

非英语母语者阅读并为 Kubernetes 文档做贡献。当你撰写内容时，请使用简单、直接的语言，句子清晰、简洁。你写的每个句子都可能被翻译成其他语言，因此请删除不增加实质内容的词语。我承认有时实践这些指导方针是具有挑战性的。

问题（issue）和拉取请求不会被翻译成其他语言。然而，当撰写问题或拉取请求的描述时，你仍然应该遵循上述指导方针。你应该在问题中添加详细信息和背景信息，以便进行分诊的人员不必应用 triage/needs-information 标签。同样，当你创建拉取请求时，你应该添加足够关于内容更改的信息，以便评审者不必去猜测拉取请求的原因。用清晰、简洁的语言提供细节可以加快流程。

观察 07: 分诊问题比应有的更困难

在 SIG Docs 中，分诊问题不仅需要能够区分文档的问题是支持请求、错误还是特性请求，还需要区分 Kubernetes 代码项目的问题。如何路由、标记和确定问题的优先级每周都在变得更容易。我仍然不完全清楚哪个 SIG 和/或项目负责文档的哪些部分。SIGs 和工作组页面有所帮助，但这还不够。在文档的页面级别，并不总是清楚哪个 SIG 或项目拥有领域专业知识。页面的 front matter 有时列出了评审者，但从未列出 SIG 或项目。每个页面都应该标明内容责任方，以便 SIG Docs 的分诊人员知道将问题路由到哪里。

观察 08: SIG Docs 人员不足

文档是软件采用的首要驱动力1。

许多贡献者只投入少量时间在 SIG Docs 上，但只有少数是受过训练的技术文档工程师。很少有公司聘请技术文档工程师至少半职投入到 Kubernetes 文档工作中。考虑到截至 2019 年，这份在线文档已从 229 个国家的读者那里获得了超过 5300 万的独立页面浏览量，这非常令人沮丧。

由于缺乏技术文档工程师，SIG Docs 面临挑战

  • 维护 Kubernetes 文档的高质量：文档有超过 750 页。这意味着需要定期检查750 页的过时内容。这不仅仅是运行链接检查器来检查 kubernetes/website 仓库。这需要人们对 Kubernetes 有技术理解，知道哪些代码发布变更会影响文档，以及知道文档中的内容位于何处，以便及时更新所有受影响的页面和示例代码文件。其他 SIGs 在这方面提供帮助，但从读者创建的问题数量来看，没有足够的人员来保持内容的及时性。
  • 减少评审和合并 PR 的时间：PR 的规模越大，获得 lgtm 标签和最终批准所需的时间就越长。我的 size/M 及更大的 PR 需要五到三十天才能获批。有时我礼貌地提醒评审者在我推送更新后再次评审。其他时候，我在 #sig-docs 频道请求任何批准者来看看并批准。人们都很忙。人们会休假。人们也会转向不涉及 SIG Docs 的新岗位，并忘记从评审者和批准者分配文件中移除自己。合并时间长的问题很大程度上是因为没有足够的评审者和批准者。另一方面是成为评审者或批准者的高门槛，远高于我在其他开源项目上看到的。经验丰富的开源技术文档工程师希望为 SIG Docs 贡献，但不能快速晋升到批准者和评审者角色。一方面，高门槛确保这些角色由具备最低水平 Kubernetes 文档知识的人员担任；另一方面，它可能会阻止经验丰富的技术文档工程师做任何贡献，或者阻止公司分配技术文档工程师给 SIG Docs。或许 SIG Docs 应该考虑偏离 Kubernetes 社区的要求，在个案基础上降低成为评审者或批准者的门槛。
  • 确保所有页面命名一致：术语应与标准化词汇表中使用的术语完全一致。保持一致性可以减少混淆。追踪并修复这些不一致之处很耗时，但对读者来说很值得。
  • 与指导委员会合作创建项目文档指导方针：Kubernetes 仓库指导方针完全没有提及文档。在项目的 GitHub 文档和 Kubernetes 文档之间，一些项目的内容几乎重复，而另一些则有冲突的内容。创建明确的指导方针，让项目知道将路线图、里程碑和详细的特性说明放在 kubernetes/<project> 仓库中，并将安装、配置、使用细节和教程放在 Kubernetes 文档中。
  • 移除重复内容：Kubernetes 用户会安装 Docker，因此一个重复内容的好例子是 Docker 安装说明。与其重复 Docker 文档中的内容，不如说明哪个版本的 Docker 与哪个版本的 Kubernetes 兼容，并链接到 Docker 文档进行安装。然后详细说明任何 Kubernetes 特定的配置。这个想法同样适用于 Kubernetes 支持的容器运行时。
  • 移除第三方供应商内容：这与移除重复内容紧密相关。一些第三方内容包括详细介绍外部产品的列表或表格。其他第三方内容出现在任务和教程部分。SIG Docs 不应负责验证第三方产品是否与最新版本的 Kubernetes 兼容。SIG Docs 也不应负责维护培训课程或云提供商的列表。此外，Kubernetes 文档不是推销供应商产品的地方。如果 SIG Docs 被迫改变不允许第三方内容的政策，可能会出现大量面向供应商或商业推广的拉取请求。维护这些内容会给 SIG Docs 带来不应有的负担。
  • 标明每个任务和教程适用的 Kubernetes 版本：这意味着需要在每个版本发布时评审每个任务和教程。读者会认为，如果某个任务或教程出现在最新版本的文档中，那么它就与最新版本的 Kubernetes 兼容。
  • 解决问题：kubernetes/website 仓库中有 470 个未解决的问题。很难跟上所有被创建的问题。我们鼓励创建简单问题的人提交 PRs：有些人会，但大多数不会。
  • 创建更详细的内容：读者在问卷中表示，他们希望看到涵盖文档所有部分（包括教程）的更详细的内容。

自 2015 年首次发布以来，Kubernetes 取得了前所未有的发展。就像任何快速增长的项目一样，它也有成长的烦恼。提供高质量且一致的文档就是其中一个烦恼，而文档对一个开源项目来说至关重要。SIG Docs 需要一个更大的技术文档撰写者核心团队，他们至少投入 50% 的时间。这样 SIG Docs 就能更好地实现目标，推进新内容的创作，更新现有内容，并及时解决未解决的问题。

观察 09：平均来说，参与技术文档项目比开发软件需要更多技能

当我对我以前的同事这么说时，他们的反应是健康的怀疑和大量的笑声。似乎许多开发者和管理者并不完全了解参与开源项目的技术文档撰写者实际做了什么。我在开发和技术文档撰写领域工作了近 22 年，注意到技术文档撰写者的价值远低于同等水平的软件开发者。

SIG Docs 核心团队成员所做的工作远不止根据需求撰写内容

  • 我们使用与开发者相同的流程和工具，例如终端、Git 工作流程、GitHub，以及 Atom, Golang, Visual Studio Code 等 IDEs；我们还使用文档专属的插件和工具。
  • 我们对细节有敏锐的洞察力，以及对设计和结构的把握：既能看到大局，也能关注细节。
  • 我们提供的文档逻辑流畅；它不仅仅是页面上的内容，而是页面如何组织到章节中，章节如何融入整体结构的方式。
  • 我们撰写的内容全面详尽，并使用非母语读者也能理解的语言。
  • 我们对英文写作有扎实的功底，并能熟练使用各种标记语言。
  • 我们具备技术能力，有时甚至达到 Kubernetes 管理员的水平。
  • 我们阅读、理解并偶尔撰写代码。
  • 我们也是项目经理，能够规划新工作并将问题分配到相应的发布版本中。
  • 在每一次代码审查和每一次对问题的评论中，我们扮演着教育者和外交官的角色。
  • 我们利用网站分析数据来规划工作，根据读者最常访问的页面以及读者反映无用的页面。
  • 我们也是调研者，定期向社区征集反馈意见。
  • 我们对整个文档进行分析，基于可用资源和读者需求，决定哪些内容应该保留，哪些应该移除。
  • 我们熟悉 Hugo 和其他用于在线文档的框架；我们知道如何创建、使用和调试 Hugo Shortcodes，这些 Shortcodes 能使内容比纯 Markdown 更强大。
  • 我们排除性能问题，不仅是 Hugo 的，还有 Netlify 的。
  • 我们努力解决 API 文档的复杂问题。
  • 我们致力于提供力所能及的最高质量文档。

如果你对 Kubernetes 文档项目的复杂性有任何疑问，可以观看 SIG Docs 主席 Zach Corleissen 的演讲

此外，文档即代码：遗失的手册 (Jennifer Rondeau, Margaret Eker；2016) 是关于文档项目普遍复杂性的一场精彩演讲。

Write the Docs 的网站和YouTube 频道是深入了解技术文档撰写中方方面面的极好地方。

想象一下，如果没有有才华、有奉献精神的技术文档撰写者，一个开源项目会变成什么样！

观察 10：社区就是一切

SIG Docs 社区以及更广泛的 Kubernetes 社区富有奉献精神、聪明、友善、有才华、有趣、乐于助人，以及许多其他积极的形容词！人们张开双臂欢迎我，不仅仅因为 SIG Docs 需要更多技术文档撰写者。我从未感到我的想法和贡献因为我是新人而被忽视。谦逊和尊重非常重要。社区成员拥有丰富的知识可以分享。参加会议，提出问题，提出改进建议，感谢他人，并尽你所能做出贡献！

特别鸣谢那些在我刚加入的时期帮助过我并忍受了我（哈哈）的人：@zacharaysarah, @sftim, @kbhawkey, @jaypipes, @jrondeau, @jmangel, @bradtopol, @cody_clark, @thecrudge, @jaredb, @tengqm, @steveperry-53, @mrbobbytables, @cblecker, and @kbarnard10。

结语

我完全理解 SIG Docs 了吗？还没有完全，但我确实理解 SIG Docs 需要更多专项资源才能持续取得成功。

引用

1 @linuxfoundation. "Megan Byrd-Sanicki, Open Source Strategist, Google @megansanicki - documentation is the #1 driver of software adoption. #ossummit." Twitter, 2019 年 10 月 29 日，凌晨 3:54, twitter.com/linuxfoundation/status/1189103201439637510。