了解文档

简介 - 新的 SIG 文档贡献者的观察

我于 2019 年 8 月开始为 SIG 文档社区做出贡献。有时我觉得自己像一个异乡人，正在适应新的社区：调查社区组织、理解贡献者社会、学习新课程和融入新的术语。我既是观察者又是贡献者。

观察 01：阅读贡献页面！

我曾为 OpenStack、OPNFV 和 Acumos 贡献过代码和文档，所以我以为为 Kubernetes 文档做贡献也会是同样的流程。我错了。我应该彻底阅读Kubernetes 文档贡献指南，而不是草草浏览一下。

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

观察 02：寻求帮助并 @ 某人

在处理我的第一个 PR 时，我对从本地克隆进行工作以及如何使我的 fork 仓库与 上游 master 同步存在疑问。我转向在互联网上搜索，而不是在 Kubernetes Slack #sig-docs 频道中提问。我使用了错误的方法来更新我的 fork 仓库，所以我不得不 git rebase 我的 PR，这根本没有顺利进行。因此，我关闭了那些 PR 并提交了新的 PR。当我在 #sig-docs 频道上寻求帮助时，贡献者发布了有用的链接，我的本地 git 配置文件应该是什么样子，以及要运行的确切 git 命令集。贡献者使用的方法与中级贡献页面中定义的方法不同。如果我事先询问应该使用哪个 GitHub 工作流程，我会节省很多时间。记录的社区知识越多，新贡献者就越容易快速实现生产力。

观察 03：不要让冲突的信息破坏你的一天

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

观察 04：信息可能分散

大型开源项目的信息分散在各种仓库中或在仓库之间重复是很常见的。有时，小组在孤岛中工作，信息没有共享。其他时候，一个人离开去从事另一个项目，而没有传授专门知识。文档存在空白，并且可能永远无法纠正，因为有更高优先级的项目。因此，新贡献者可能难以找到基本信息，例如会议详情。

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

观察 05：耐心是一种美德

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

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

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

  • 总体而言，语法和标点符号是否正确？
  • 内容是否清晰、简洁，并且适合非母语人士？
  • 内容的风格是否与文档的其余部分相符？
  • 内容的流程是否合理？
  • 是否可以更改任何内容以使内容更好，例如使用 Hugo shortcode？
  • 内容是否正确呈现？

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

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

观察 06：让每个词都有价值

非英语母语者会阅读并为 Kubernetes 文档做出贡献。在编写内容时，请使用简单、直接的语言，以清晰、简洁的句子表达。您写的每个句子都可能会被翻译成另一种语言，因此请删除不添加实质内容的单词。我承认，在某些时候实施这些准则具有挑战性。

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

观察 07：问题分类比它应该的更困难

在 SIG Docs 中，问题分类需要能够区分文档以及 Kubernetes 代码项目的支持、错误和功能请求。如何路由、标记和优先处理问题已变得越来越容易。我仍然不 100% 清楚哪个 SIG 和/或项目负责文档的哪些部分。SIG 和工作组页面有所帮助，但这还不够。在文档的页面级别，哪个 SIG 或项目具有领域专业知识并不总是很明显。页面的前言有时会列出审阅者，但从不列出 SIG 或项目。每个页面都应指示谁负责内容，以便 SIG Docs 分类人员知道将问题路由到何处。

观察 08：SIG Docs 人员不足

文档是软件采用的第一大驱动力¹。

许多贡献者只在 SIG Docs 上投入少量时间，但只有少数人是受过培训的技术作家。很少有公司聘请技术作家至少兼职从事 Kubernetes 文档的工作。对于截至 2019 年，有来自 229 个国家/地区的读者访问量超过 5300 万次的在线文档来说，这非常令人沮丧。

由于缺乏技术作家，SIG Docs 面临挑战

• 在 Kubernetes 文档中保持高质量：文档有 750 多页。需要定期检查750 页的内容是否过时。这不仅包括针对 kubernetes/website 仓库运行链接检查器。这还包括人们对 Kubernetes 的技术理解、了解哪些代码发布更改会影响文档，以及了解内容在文档中的位置，以便及时更新所有受影响的页面和示例代码文件。其他 SIG 会提供帮助，但根据读者创建的问题数量来看，没有足够的人员致力于保持内容新鲜。
• 缩短审阅和合并 PR 的时间：PR 的规模越大，获得 lgtm 标签和最终批准所需的时间就越长。我的 size/M 和更大的 PR 需要 5 到 30 天才能获得批准。有时，在推送更新后，我会礼貌地提醒审阅者再次审阅。有时，我会在 #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：有些人会这样做，但大多数人不会。
• 创建更详细的内容：读者表示他们希望看到文档的所有部分，包括教程，都有更详细的内容。

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

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

当我把这句话告诉以前的同事时，他们的反应是强烈的怀疑和哄堂大笑。似乎许多开发人员以及管理人员并不完全了解技术写作者为开源项目贡献内容时实际在做什么。在从事开发和技术写作 22 年的大部分时间里，我注意到技术写作者的价值远低于同等水平的软件开发人员。

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

• 我们使用与开发人员相同的一些流程和工具，例如终端、git 工作流程、GitHub 和 IDE（如 Atom、Golang 和 Visual Studio Code）；我们还使用特定于文档的插件和工具。
• 我们拥有对细节以及设计和组织良好的眼光：既注重整体也注重细节。
• 我们提供的文档具有逻辑流程；它不仅仅是页面上的内容，还包括页面如何融入章节，章节如何融入整体结构。
• 我们编写的内容是全面的，并且使用的语言是母语非英语的读者也能理解的。
• 我们熟练掌握使用各种标记语言进行的英语写作。
• 我们具有技术性，有时达到 Kubernetes 管理员的水平。
• 我们会阅读、理解，偶尔还会编写代码。
• 我们是项目经理，能够计划新工作，并将问题分配给不同的版本。
• 我们是教育者和外交家，在我们进行的每一次审查和在问题上留下的每一条评论中都体现着这一点。
• 我们使用网站分析来规划工作，根据读者最常访问的页面以及读者认为无用的页面来制定计划。
• 我们是调查员，定期从社区征求反馈。
• 我们作为一个整体分析文档，根据可用资源和读者需求，决定保留哪些内容，删除哪些内容。
• 我们对 Hugo 和其他用于在线文档的框架有实践知识；我们知道如何创建、使用和调试 Hugo 短代码，这些短代码使内容比纯 Markdown 更健壮。
• 我们不仅可以解决 Hugo 的性能问题，还可以解决 Netlify 的性能问题。
• 我们正在努力解决 API 文档的复杂问题。
• 我们致力于提供尽可能高质量的文档。

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

• 多语言 Kubernetes - kubernetes.io 堆栈，我们是如何到达那里的，以及到达那里需要什么
• 翻译中的发现：开源本地化一年的经验教训

此外，文档即代码：缺失的手册（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 需要更多专用资源才能继续取得成功。

引文

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

• ←上一篇
下一篇→