文档
Fri, Dec 20, 2019

在 Google Season of Docs 2019 中与 Apache Airflow 的经历

Kartik Khare

我几乎是偶然间接触到 Google Season of Docs (GSoD) 的，这要归功于我对 HackerNews 和 Twitter 的高度沉迷。我熟悉 Google Summer of Code，但对这个项目却不熟悉。事实证明这是它的启动阶段。我阅读了详细信息，整个过程感觉与 GSoC 非常相似，只不过它侧重于文档。

关于我

在过去的 1.5 年里，我一直在 medium 和我的博客上撰写技术文章。写博客可以帮助我检验对概念的理解，因为用简单的句子理清最复杂的想法需要投入大量时间。

此外，我在过去三年里一直担任软件开发者，这也包括为我的项目编写文档。我本科毕业于 IIT Roorkee。在大学期间，我曾申请过一次 GSoC，但最终未入选。

我认为 GSoD 是一个绝佳的机会，可以利用开源社区的反馈来提升我的技术写作技能。我曾为 Apache Superset 和 Apache Druid 贡献了一些错误修复和功能，但这将是我第一次以技术写作者的身份做出贡献。

寻找组织

约有 40 多家组织参与了 GSoD。然而，有两个组织第一时间就让我觉得很合适。第一个是 Apache Airflow，因为我之前已经广泛使用过 Airflow，并且在我前公司的分支版本中贡献了一些自定义操作符。

第二个是 Apache Cassandra，我也曾广泛使用过它，但没有做过任何代码或文档修改。

综合考虑我的经验，我决定选择 Airflow。

项目选择

选择组织后，下一步是选择项目。同样，我之前的经验在这里也发挥了作用，最终我选择了如何创建工作流。该项目的目标是编写文档，帮助用户创建复杂以及自定义的 DAG。
不过，最终的交付成果有些不同。稍后再详细介绍。

提交申请后，我便忙于工作，直到有一天，我收到了谷歌的邮件，确认我被选中担任该项目的技术写作者。

社区融合

被选中只是一个开始。我受邀加入了 Airflow 的 Slack 频道，大多数讨论都在那里进行。我的导师是来自 Apache Airflow 的 Ash-Berlin Taylor。我开始与我的导师交流，大致了解预期的交付成果。交付成果记录在 confluence 中。

  • 关于如何创建 DAG 的页面，其中还包括
    • 修订关于 DAG 调度相关的页面
    • 添加关于特定 DAG 条件的提示，例如重新运行失败的任务
  • 关于开发自定义操作符的页面，其中包括
    • 描述创建操作符时重要的机制，例如模板字段、UI 颜色、钩子、连接等。
    • 描述操作符和钩子之间的职责
    • 处理共享资源（例如连接和钩子）时的注意事项
  • 描述如何定义任务之间关系的页面。该页面应包含有关以下内容的信息：
    • ** >> << **
    • 设置上游 / 设置下游
    • 辅助方法，例如 chain
  • 描述任务间通信的页面，其中还包括
    • 修订与宏和 XCOM 相关的页面

我的导师很早就明确表示，交付成果更像是指导方针，而不是严格的规则。如果我愿意，我也可以选择从事与项目相关的其他工作，即使这些工作不在交付成果范围内。与导师联系后，我开始与整个 Airflow 社区互动。社区里的人都很乐于助人，特别是 Kamil Bregula。Kamil 帮助我了解了在为 Airflow 编写文档时需要遵循的指导方针。

文档开发

我选择了 DAG 运行作为我的第一个交付成果。我选择这个主题是因为其中一些部分已经有文档了，但还需要补充一些文本。我将现有的“调度与触发器 (Scheduling & Triggers)”页面拆分成了两个新页面。

  1. 调度器
  2. DAG 运行

大部分与调度器无关的细节被移至 DAG 运行页面，然后补充了诸如如何重新运行任务或 DAG 之类的遗漏点。当我对我的版本满意后，我请我的导师和 Kamil 进行评审。第一个版本中，我在 Google Docs 文件中分享了文本，评审者在其中添加了评论。然而，文档开始变得混乱，难以追踪更改。现在是时候发起一个正式的 Pull Request 了。

就在此时，我遇到了第一个挑战。Apache Airflow 的文档是使用 RST (reStructuredText) 语法编写的，我对此完全不熟悉。我之前主要使用 Markdown。接下来的几天我花时间学习了这种语法。幸运的是，很快就熟悉了。我发起了 Pull Request，等待评论。几天后，当我看到评论时，它们主要集中在两个方面——语法和格式。还有一些评论涉及到我遗漏或误解的部分。

使用正确的语法

与 Kamil 讨论后，我决定遵循 谷歌开发者文档指南。这些指南包含了编写优秀文档时几乎所有需要考虑的事项，例如总是使用主动语态。其次，我安装了 Grammarly 应用。写完文档后，我通常会将它放到 Grammarly 中检查错误。然后我纠正错误，做一些修改，再把它放到 Grammarly 中。这是一个迭代过程，直到我得到了一个语法正确但又不像是由 AI 生成的文档版本。

格式化

格式化包括编写注释和提示，在文本中正确标记 Airflow 组件，并确保快速浏览文档的用户不会错过关键信息。这需要一些反复试验。我研究了 Airflow 文档当前的格式模式，然后进行修改，提交，采纳新的评审意见，以此类推。

最终，所有评审者都批准了 PR，但直到两个月后才合并。这是因为我们怀疑是否应该将更多页面（例如概念）也拆分，从而形成结构更佳的文档。最后，我们决定推迟合并，直到与更广泛的社区进行讨论。

我的第二个 PR 是一份全新的文档。这份文档是关于如何创建自定义操作符的。这一次，由于我已经熟悉了大部分语法，我直接发起了 PR，而没有通过 Google Docs。我再次收到了很多评论，但这次更多的是关于我写了什么，而不是我如何写。例如，详细描述如何使用模板字段并清理我的代码示例。语法和格式错误的评论数量减少表明我取得了进展。这个 PR 在两周内被接受，这极大地增强了我的信心。

我的第二个 PR 之后，我陷入了僵局。我剩下的最后一个交付成果与宏有关，但范围尚不明确。我与我的导师谈了谈，他告诉我，如果我在社区弄清楚需要哪些更改的同时选择偏离原计划去做其他事情，他并不介意。我们讨论了很多想法。最后，我决定根据我的导师在一次聚会中关于 Apache Airflow 的讲座，编写一份最佳实践指南。由于我自己也曾在使用 Airflow 生产环境中遇到挑战，我非常有动力写这样一份文档，以便其他开发者不再受苦。初稿在两周内完成。我将其命名为在生产环境中运行 Airflow。然而，在文档中添加更多内容后，我意识到最好称其为最佳实践指南，大多数开源项目都有这类指南。

很多人对这份pull request 充满热情，因为他们中的许多人也面临着文档中描述的挑战。我抓住了要害。经过接下来一两周的讨论，我的 PR 被接受了。

然后我回到我的第一个 PR，开始根据新的评审意见进行一些修改。之后，我与导师讨论了一些困扰他的具体细节，例如如何用尽可能少的文字让人们理解调度间隔的工作原理。经过大量的反复试验，我们得到了一个我们双方都满意的版本。

最终评估

9 月 12 日，我收到了谷歌关于项目成功完成的邮件。这意味着我的导师对我的工作很满意。Airflow 社区也对我的贡献表示赞赏。

我的文档最终在 Airflow 网站上发布了 -

我也开始被邀请参与其他开发者的 PR 评审。我期待在来年为项目做出更多贡献。

分享