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

21-12-28 banq

许多技术问题最终会变成人的问题,缺乏良好的文档也不例外。编写和维护文档是一种需要鼓励和培养的习惯。不幸的事实是,如果没有文档文化,再多的工具也无济于事。今天,我们将看看 3 家高性能工程公司,Google、Twitter 和 Spotify,如何处理他们的技术文档并建立文档文化。

 

谷歌

Riona MacNamara在2016年发表了一篇精彩的演讲,讲述了她在谷歌改善其内部文档状况的工作。我们强烈建议你观看这个演讲(只有30分钟),但这里有一些他们在2014年时面临的问题的有趣亮点。

  • 48%的谷歌工程师认为糟糕的文档是第一生产力问题
  • 50%以上的SRE问题提到了文档的问题
  • 文档被认为是每个人的问题,但没有人负责的工作

每个人都感受到了不良文档的痛苦。尽管过去做了很多努力,但都没有成功。文件仍然分散在维基、随机文件中,甚至是离线的白板上。将技术写手嵌入团队会有一段时间的帮助,但写手离开后,文档会迅速恶化。

那么,是什么让他们开始改变现状的呢?他们用一个叫做g3docs的系统从根本上简化了工程师的文档。它做到了以下几点。

  • 移除决定--提出一种方法来记录事情
  • 把文档放在Markdown的源代码旁边,这样工程师就可以留在他们的IDE中了
  • 文档在提交时被自动渲染成漂亮的HTML页面

在他们所做的工具工作的基础上,该团队还到处创造组织变革。

  • 与有影响力的工程师结成联盟,引入工具。
  • 与特定的团队合作,建立战略集成
  • 在公开场合进行发布和迭代
  • 不强迫团队采用新的工作流程--以身作则

在g3docs被采用后,使用量增长到每月20万+文档更新和390万页面浏览量(注意:这些数字是2016年的)。

  

Twitter

早在2014年,Twitter有3名技术文档写手。在其他方面,他们的职责是协助1000多名软件工程师编写内部文档。同时,在Twitter,围绕着文档的总体氛围是不完整的、过时的,甚至是不存在的。大多数文档都在Confluence中,但也有一些是在Google Docs或READMEs中。

Simeon Franklin和Marko Gargenta有一个很棒的演讲,他们讨论了他们采取的策略。与谷歌类似,他们开始了改变人们对文档的看法的旅程。

他们提出了软件工程师和测试的例子:不久前,人们还不期望软件工程师写测试。这种期望已经被颠覆了,今天,未经测试的代码是不被看好的。他们想在Twitter的内部对文档做同样的事情。

他们的方法包括三个部分。

  • 通过教育和特殊的DocDays来鼓励文档工作
  • 建立一个新的文档即代码的堆栈(DocBird)。
  • 创建文档模板

他们组织了DocDays,这是一个单日的黑客活动,开发人员在此更新他们的文档。技术作家会在这一天提供培训,并帮助编辑最终的文档。这些日子的更大目的是将文档写作作为一种实践来宣传和规范。它建立了社区和一套共同的关于文档的期望。

为了使文档编写更容易和标准化,他们推出了一个新的文档即代码的堆栈,叫做DocBird,它是一个围绕Sphinx的定制包装。与g3docs类似,它从源头自动构建你的文档。它消除了 "文档在哪里 "的问题。

最后,他们为文档创建了共享模板。这些模板有共同的部分和问题,可以被复制到项目中作为起点使用。盯着一张空白的画布有时是开始写作的最困难的部分。

  

Spotify

让Spotify的故事变得有趣的是,他们已经在一个叫做Backstage的项目中开源了他们用于文档方法的大部分堆栈。

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

在内部,我们叫它TechDocs。到目前为止,它是Spotify使用最多的插件--占我们Backstage流量的20%(尽管它只是130多个插件中的一个)。

Spotify使用Backstage的文档即代码的过程就像我们以前的案例研究一样:工程师们认为第三大问题是无法找到他们工作所需的技术文档。文档分散在Confluence、Google Docs和自定义网站上,而且什么都找不到。

Gary Niemen有一个演讲,他讨论了他们团队在建立Spotify的 "文档即代码+"基础设施方面的工作。他强调了一些有趣的经验。

  • 保持解决方案的简单性--这样它就能发挥作用
  • 对工程师进行严格的优化
  • 标准化和集中化

他们的技术写作团队的目标是让工程师在1分钟内将他们的文档从 "卡住到解开"。他们继续朝着这个目标迈进。

  

从中学习什么?

这些故事中有很多共同的主题,但这些经验可以归结为三个要点。

  • 让工程师的生活尽可能简单--消除摩擦
  • 对你的工具进行标准化和投资
  • 通过教学和以身作则使文档成为一种期望

我们在这三个案例中所看到的,许多读者根据经验可能会同意,工程师不会在维基中维护文档。从你的代码转移到一个单独的系统,并且不能使用你现有的工具,这种背景转换意味着文档会被遗忘。在这些例子中,三家公司都采用了 "文档即代码 "的方法,因为它使开发人员在更新文档时无障碍。

这三家公司也都在工具方面进行了大量的投资。无论你为你的文档堆栈选择什么(我们显然坚信Doctave是一个优秀的解决方案),坚持下去,并确保这是技术文档的唯一地方。关于文档的位置,不应该有任何疑问。

最后,这可能是最难的部分,你需要让文档成为工程文化的一部分。这意味着教开发人员如何写文档,提供使用的例子和模板,组织专门针对文档的黑客日,并与你的组织中具有影响力的工程师合作以设定期望。就像今天测试如何成为大多数工程师接受的规范一样,文档也可以。

 

猜你喜欢