Google、Twitter 和 Spotify 如何建立文档文化

许多技术问题最终归结为人为问题，缺乏良好的文档也不例外。编写和维护文档是一种需要鼓励和培养的习惯。然而，令人遗憾的是，如果没有文档文化，再多的工具也无济于事。今天，我们将探讨谷歌、Twitter 和 Spotify 这三家高绩效工程公司是如何管理其技术文档并建立文档文化的。

谷歌

2016 年，Riona MacNamara发表了一场精彩的演讲，讲述了她在 Google 工作期间如何改进内部文档的现状。我们强烈建议您观看这场演讲（时长约 30 分钟），以下是他们在 2014 年遇到的一些有趣问题：

• 48% 的 Google 工程师认为糟糕的文档是影响生产力的首要问题
• 50% 以上的 SRE 问题与文档有关
• 文档被认为是每个人的问题，但不是任何人的工作

每个人都深感文档质量低劣的痛苦。尽管过去付出了无数努力，却毫无成效。文档仍然散落在 wiki、随机文档，甚至离线的白板上。在团队中安插技术写手或许能暂时缓解问题，但一旦他们离开，文档质量很快就会下降。

那么，是什么让他们开始改变现状呢？他们用一个名为g3docs的系统，为工程师们大大简化了文档编写。该系统的功能如下：

• 消除决策——提供一种记录事物的方式
• 使用 Markdown 将文档托管在源代码旁边，以便工程师可以留在他们的 IDE 中
• 文档在提交时自动呈现为漂亮的 HTML 页面

除了进行工具开发工作之外，团队还积极推动组织变革：

• 与有影响力的工程师结成联盟，推出工具
• 与特定团队合作建立战略整合
• 公开发布和迭代
• 永远不要强迫团队采用新的工作流程——以身作则

采用 g3docs 后，使用量增长到每月 200K+ 文档更新和 390 万页面浏览量（注：这些数字来自 2016 年）。

叽叽喳喳

2014年，Twitter 有3名技术文档撰写员。他们的职责之一是协助1000多名软件工程师编写内部文档。当时，Twitter 的文档普遍不完整、过时，甚至没有文档。大多数文档存储在 Confluence 中，但也有一些存储在 Google Docs 或 README 中。

Simeon Franklin和Marko Gargenta进行了一场精彩的演讲，探讨了他们所采取的策略。与谷歌类似，他们也踏上了一段改变人们对于文档的看法的旅程。

他们举了软件工程师和测试的例子：不久前，软件工程师还不需要编写测试。如今，这种要求已经发生了改变，未经测试的代码会遭到反对。他们希望在 Twitter 内部对文档采取同样的措施。

他们的方法分为三个部分：

• 通过教育和特殊DocDays鼓励记录
• 构建新的文档即代码堆栈（DocBird）
• 创建文档模板

他们组织了DocDays，这是一种为期一天的黑客马拉松，开发者们可以在其中更新文档。技术作家会在当天进行培训，并协助编辑最终文档。这些活动更大的目的是推广和规范文档写作的实践。它有助于建立社区并形成一套关于文档的共同期望。

为了使文档编写更加便捷和标准化，他们推出了一个名为 DocBird 的新文档即代码 (docs-as-code) 堆栈，它是Sphinx的定制包装器。与 g3docs 类似，它会自动从源代码构建文档。它消除了“文档在哪里”的疑问。

最后，他们创建了用于文档的共享模板。这些模板包含通用章节和问题，可以复制到项目中作为起点。面对空白的画布有时是写作最难的部分。

Spotify

Spotify 的故事之所以有趣，是因为他们已经在一个名为Backstage的项目中开源了用于文档方法的大部分堆栈。

Backstage 是 Spotify 众多微服务的软件目录。它拥有丰富的功能和插件，但最受欢迎的功能之一是集成的文档即代码支持。

我们内部称之为 TechDocs。它是 Spotify 目前使用率最高的插件，约占我们 Backstage 流量的 20%（尽管它只是 130 多个插件中的一个）。

Spotify 迈向 Backstage 文档即代码的旅程，其起点与我们之前的案例研究一样：工程师们认为，第三大问题是无法找到完成工作所需的技术文档。文档分散在 Confluence、Google Docs 和自定义站点上，根本找不到任何内容。

Gary Niemen做了一次演讲，讨论了他们的团队在构建 Spotify 的“文档即代码+”基础设施方面所做的工作。他强调了一些有趣的经验：

• 保持解决方案简单——这样它才能有效
• 为工程师进行激烈优化
• 标准化和集中化

他们为技术写作团队设定的目标是，让工程师在一分钟内就能掌握文档编写的“诀窍”。他们正在不断努力，朝着这个目标迈进。

我们能学到什么？

这些故事有很多共同的主题，但经验教训可以归结为三个要点：

• 让工程师的工作尽可能轻松——消除摩擦
• 标准化并投资于您的工具
• 通过教学和示范，使记录成为一种期望

我们从这三个案例中看到，很多读者可能也会根据经验认同，工程师不会在 wiki 中维护文档。从代码迁移到独立系统，并且无法使用现有工具，这种上下文切换意味着文档会被遗忘。在这三个案例中，这三家公司都采用了“文档即代码”的方法，因为它让开发人员更新文档变得非常顺畅。

这三家公司都在工具方面投入了巨资。无论您选择哪种文档堆栈（我们坚信Doctave是一个优秀的解决方案），都请坚持使用，并确保它是技术文档的唯一存储位置。文档存放在哪里永远不应该成为问题。

最后，这很可能是最难的部分，你需要让文档成为工程文化的一部分。这意味着你需要教开发人员如何编写文档，提供可用的示例和模板，组织专门用于文档的“黑客日”，并与组织中具有影响力的工程师合作设定预期目标。正如测试如今已成为大多数工程师接受的规范一样，文档也应如此。