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

探索文档

作者：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 仓库，然后将工作推送到自己的派生仓库，再创建拉取请求。我按照“开始贡献”页面中提交拉取请求部分的说明，创建了一个简单的拉取请求（PR）。该部分描述了如何使用 GitHub UI 进行文档更改。我了解到，这种方法对于只需要一次提交即可修复的更改是可行的。但是，当您必须对 PR 进行额外更新时，此方法会变得复杂。每次使用 GitHub UI 进行更改时，GitHub 都会创建一个新的提交。Kubernetes GitHub 组织要求压缩提交。 “开始贡献”页面没有提及压缩提交，所以我查看了 GitHub 和 git 文档。我无法使用 GitHub UI 压缩我的提交。我必须在本地 `git fetch` 和 `git checkout` 我的拉取请求，使用命令行压缩提交，然后推送我的更改。如果“开始贡献”提及了压缩提交，我就会从本地克隆开始工作，而不是使用 GitHub UI。

观察 02：主动联系某人

在处理我的第一个 PR 时，我对从本地克隆工作以及如何使我的派生与 `upstream master` 保持同步有疑问。我选择在互联网上搜索，而不是在 Kubernetes Slack #sig-docs 频道提问。我使用了错误的流程来更新我的派生，所以我不得不 `git rebase` 我的 PR，结果非常糟糕。因此，我关闭了这些 PR 并提交了新的。当我在 #sig-docs 频道寻求帮助时，贡献者们发布了有用的链接，我的本地 git 配置文件应该是什么样子，以及要运行的准确的 git 命令集。贡献者使用的流程与“中级贡献”页面中定义的流程不同。如果我早点询问应该使用哪种 GitHub 工作流程，我本可以节省大量时间。社区知识记录得越多，新贡献者就越容易快速提高生产力。

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

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

观察 04：信息可能分散

对于大型开源项目来说，信息分散在各个仓库或在仓库之间重复是很常见的。有时团队各自为政，信息不共享。有时，一个人离开了去从事不同的项目，而没有传承专业知识。文档空白存在，并且由于优先级较高的事项可能永远无法纠正。因此，新贡献者可能难以找到基本信息，例如会议详情。

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

观察 05：耐心是一种美德

贡献者可能需要等待数天才能获得对大型 PR 的反馈。从提交到最终批准的过程可能需要数周而不是数天。原因有二：1）大多数审阅者在 SIG Docs 上是兼职工作；2）审阅者希望提供有意义的审阅。“随手审阅”在 SIG Docs 中是不存在的！审阅者会检查以下内容：

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

  • PR 是否遵循样式和内容指南中的指导原则？

    • 总的来说，语法和标点符号是否正确？
    • 内容是否清晰、简洁，并且适合非母语人士阅读？
    • 内容风格是否与文档其余部分保持一致？
    • 内容流程是否合理？
    • 是否可以更改任何内容以使内容更好，例如使用 Hugo 短代码？
    • 内容是否正确渲染？

  • 内容在技术上是否正确？

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

观察 06：惜字如金

非英语母语者阅读并贡献 Kubernetes 文档。在撰写内容时，请使用简洁明了的语言和清晰简洁的句子。您写的每个句子都可能被翻译成其他语言，因此请删除不增加实质内容的词语。我承认，有时实施这些准则具有挑战性。

问题和拉取请求不会被翻译成其他语言。但是，在编写问题或拉取请求的描述时，您仍然应该遵循上述准则。您应该为问题添加详细信息和背景信息，以便分流人员不必应用 `triage/needs-information` 标签。同样，当您创建拉取请求时，您应该添加足够多的关于内容更改的信息，以便审阅者不必费力找出拉取请求的原因。以清晰简洁的语言提供详细信息可以加快流程。

观察 07：分流问题比预想的要困难

在 SIG Docs 中，对问题进行分类需要能够区分支持请求、错误报告和功能请求，不仅针对文档，还针对 Kubernetes 代码项目。周复一周，如何路由、标记和确定问题的优先级变得越来越容易。我仍然不完全清楚哪个 SIG 和/或项目负责文档的哪些部分。SIG 和工作组页面有所帮助，但这还不够。在文档的页面级别，哪个 SIG 或项目具有领域专业知识并不总是显而易见的。页面的前言有时会列出审阅者，但从不列出 SIG 或项目。每个页面都应指明谁负责内容，以便 SIG Docs 分流人员知道如何路由问题。

观察 08：SIG Docs 人手不足

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

许多贡献者在 SIG Docs 上投入少量时间，但只有少数是受过培训的技术文档撰写人员。很少有公司雇佣技术文档撰写人员至少兼职在 Kubernetes 文档上工作。这对于在线文档来说非常令人沮丧，因为该文档在 2019 年迄今已吸引了来自 229 个国家的读者超过 5300 万独立页面浏览量。

由于缺乏技术写作人员，SIG Docs 面临挑战

  • **维护 Kubernetes 文档的高质量**：文档超过 750 页。这意味着需要定期检查**750 页**的过期内容。这不仅仅是针对 `kubernetes/website` 仓库运行链接检查器。这涉及到人员对 Kubernetes 具备技术理解，了解哪些代码发布更改会影响文档，以及知道内容在文档中的位置，以便**所有**受影响的页面和示例代码文件都能及时更新。其他 SIG 会为此提供帮助，但根据读者创建的问题数量来看，没有足够的人员致力于保持内容的新鲜度。
  • **缩短 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 个未解决的问题。很难跟上所有创建的问题。我们鼓励那些创建更简单问题的人提交 PR：有些人会这样做；大多数人不会。
  • **创建更详细的内容**：读者表示他们希望在文档的所有部分，包括教程中，看到更详细的内容。

Kubernetes 自 2015 年首次发布以来，经历了前所未有的增长。和任何快速发展的项目一样，它也有成长的烦恼。提供始终如一的高质量文档就是其中一个烦恼，也是一个对开源项目来说极其重要的烦恼。SIG Docs 需要一个更大的核心技术写作团队，至少分配 50% 的时间。这样，SIG Docs 就能更好地实现目标，推进新内容，更新现有内容，并及时解决未解决的问题。

观察 09：贡献技术文档项目平均需要比开发软件更多的技能

当我对我以前的同事这么说时，他们的反应是健康的怀疑和许多笑声。似乎许多开发人员和经理都不完全了解技术写作者为开源项目贡献的实际工作。在从事开发和技术写作 22 年的大部分时间里，我注意到技术写作者的价值远低于同等水平的软件开发人员。

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

  • 我们使用与开发人员相同的某些流程和工具，例如终端、git 工作流、GitHub 以及 Atom、Golang 和 Visual Studio Code 等 IDE；我们还使用文档特定的插件和工具。
  • 我们对细节以及设计和组织有敏锐的洞察力：既有大局观，也有微观视角。
  • 我们提供具有逻辑流程的文档；它不仅仅是页面上的内容，而是页面如何融入章节，以及章节如何融入整体结构。
  • 我们撰写内容全面，使用的语言能够让不精通英语的读者理解。
  • 我们熟练掌握使用各种标记语言的英语写作。
  • 我们是技术人员，有时达到 Kubernetes 管理员的水平。
  • 我们阅读、理解并偶尔编写代码。
  • 我们是项目经理，能够规划新工作并将问题分配到发布版本。
  • 我们在每次审查和每次对问题发表评论时，都扮演着教育者和外交家的角色。
  • 我们利用网站分析，根据读者最常访问的页面以及读者认为无用的页面来规划工作。
  • 我们是调查员，定期征求社区反馈。
  • 我们从整体上分析文档，根据可用资源和读者需求，决定哪些内容应该保留，哪些内容应该删除。
  • 我们掌握 Hugo 和其他用于在线文档的框架的实用知识；我们知道如何创建、使用和调试 Hugo 短代码，使内容比纯 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 和 @kbarnard10。

结语

我是否深入理解了 SIG Docs？还没有完全理解，但我确实明白 SIG Docs 需要更多专注的资源才能继续取得成功。

参考文献

1 @linuxfoundation。“Megan Byrd-Sanicki，开源策略师，谷歌 @megansanicki - 文档是软件采用的第一驱动力。#ossummit。” Twitter，2019 年 10 月 29 日，上午 3:54，twitter.com/linuxfoundation/status/1189103201439637510。