寻求 SRE

第19章 更好地使用文档：将文档融入工程工作流程

本作品已使用人工智能进行翻译。欢迎您提供反馈和意见：[e-mail]

Ríona MacNamara 和 Shylaja Nukala，以及谷歌的 Stas Miasnikoŭ、Aaron Gillies、Jeremy Sharpe 和微软的 Niall Richard Murphy。

在整个软件行业，人们对工程文档的信心不足。Stack Overflow 的 2016 年开发人员调查将文档列为开发人员面临的第二大挑战。

这是一个问题。缺失、不完整、陈旧或不准确的文档会损害开发速度、软件质量，对于 SRE 而言，关键在于服务可靠性。而由此产生的挫败感可能是导致开发人员工作不愉快的主要原因。

文档需要花费时间和精力，这对 SRE 来说尤其具有挑战性。SRE 通常将 35% 的时间花在运营工作上，只有 65% 的时间用于开发。花在文档上的时间需要从开发预算中支出，而如果认为创建和维护文档是一项粗糙的工作，在绩效考核和晋升过程中可能得不到认可或奖励，那么这就具有挑战性。

如何改变这种观念？如何让组织了解工程文档的价值，鼓励工程师创建和维护文档，并让管理层和领导层相信这样做是一项值得认可、资助和奖励的活动？

在谷歌，我们很幸运拥有一个强大的技术文档撰写组织，但我们的撰写人员往往专注于影响力大、知名度高的项目。事实上，大多数工程和 SRE 团队都需要创建和维护自己的文档，他们并不总是觉得这很容易，也不总是觉得这很吸引人。不过，自 2015 年以来，我们在提高内部工程信息的质量和可用性方面取得了重大进展。在本章中，我们将分享我们的心得并提供建议，希望这些建议对希望更好地完成文档工作的 SRE、SWE 或技术撰稿人有所帮助。我们特别关注以下几点：

定义文档质量

我们提出了定义文档质量的框架和词汇，并展示了（重点是 SRE 操作）如何使用这些框架和词汇来定义文档要求。

将文档融入工程工作流程

文档是工程工作的核心部分。理论上是这样！在实践中，文档的创建和维护往往需要昂贵的上下文切换，因此往往被忽视。我们将分享将文档与代码库和工作流程工具相结合的经验。

宣传文档的价值

要推动组织变革，说服领导层相信文档工作值得投资，就必须能够传达文档工作对业务的影响。

文档可能确实没有完全融入当今的工程实践。幸运的是，我们可以从一个先例中获得灵感、词汇和模型：软件测试。十年前，测试的情况与文档的情况如出一辙：临时、不规范、不可预测。如今在谷歌，单元测试、回归测试和集成测试都已深深融入工程流程和工具中，将未经测试的代码推向生产根本不现实。在谷歌，测试是一种严格的、被高度认可的做法，已经完全融入了工程工作流程。对于文档，我们也可以这样做。

定义质量：好文档是什么样的？

从本质上讲，文档质量的定义很简单：

当文件达到目的时，它就是好文件。

但在衡量或报告文档质量之前，我们需要一个描述文档质量的词汇。在本节中，我们将提出一个直接来自软件测试领域的词汇，用于描述软件质量的各个方面。从根本上说，文档质量有两个方面--结构质量和功能质量--它们对文档的整体质量都有贡献。

在描述技术文档时，人们通常会想到结构质量，而当技术撰稿人称自己为 "文字匠 "时，他们肯定会引用结构质量。结构质量描述的是文档应该是什么样的。如果文档或文档集符合以下标准，那么它的结构质量就很高：

• 拼写和语法正确

• 符合风格和使用指南

• 使用正确的语音和语调

• 条理清晰，易于浏览

结构质量相对容易确定：拼写是否正确；风格是否符合要求；链接是否有效。这种易于衡量的特点很容易让人将结构质量作为文档集质量的默认衡量标准。如果根据文档的结构质量来衡量和评估您的文档，就很容易过分强调结构质量而忽略整体质量。文档只需满足其目的即可，与面向客户的内容相比，描述一个不断变化的系统的面向内部的文档需要较低水平的润色和风格。 ...