许多技术问题最终会变成人的问题，缺乏良好的文档也不例外。编写和维护文档是一种需要鼓励和培养的习惯。不幸的事实是，如果没有文档文化，再多的工具也无济于事。今天，我们将看看 3 家高性能工程公司，Google、Twitter 和 Spotify，如何处理他们的技术文档并建立文档文化。
谷歌
Riona MacNamara在2016年发表了一篇精彩的演讲，讲述了她在谷歌改善其内部文档状况的工作。我们强烈建议你观看这个演讲（只有30分钟），但这里有一些他们在2014年时面临的问题的有趣亮点。
- 48%的谷歌工程师认为糟糕的文档是第一生产力问题
- 50%以上的SRE问题提到了文档的问题
- 文档被认为是每个人的问题，但没有人负责的工作
每个人都感受到了不良文档的痛苦。尽管过去做了很多努力，但都没有成功。文件仍然分散在维基、随机文件中，甚至是离线的白板上。将技术写手嵌入团队会有一段时间的帮助，但写手离开后，文档会迅速恶化。
那么，是什么让他们开始改变现状的呢？他们用一个叫做g3docs的系统从根本上简化了工程师的文档。它做到了以下几点。
- 移除决定--提出一种方法来记录事情
- 把文档放在Markdown的源代码旁边，这样工程师就可以留在他们的IDE中了
- 文档在提交时被自动渲染成漂亮的HTML页面
在他们所做的工具工作的基础上，该团队还到处创造组织变革。
- 与有影响力的工程师结成联盟，引入工具。
- 与特定的团队合作，建立战略集成
- 在公开场合进行发布和迭代
- 不强迫团队采用新的工作流程--以身作则
在g3docs被采用后，使用量增长到每月20万+文档更新和390万页面浏览量（注意：这些数字是2016年的）。
早在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是一个优秀的解决方案），坚持下去，并确保这是技术文档的唯一地方。关于文档的位置，不应该有任何疑问。
最后，这可能是最难的部分，你需要让文档成为工程文化的一部分。这意味着教开发人员如何写文档，提供使用的例子和模板，组织专门针对文档的黑客日，并与你的组织中具有影响力的工程师合作以设定期望。就像今天测试如何成为大多数工程师接受的规范一样，文档也可以。