PDF为什么 SRE 文档很重要
文档如何帮助 SRE 团队管理新的和现有的服务
Shylaja Nukala 和 Vivek Rau
SRE（站点可靠性工程）是一种职位职能、一种思维模式，以及一套工程方法，用于使 Web 产品和服务可靠地运行。 SRE 在软件开发和系统工程的交叉点运作，以解决运营问题并设计解决方案，从而可扩展、可靠且高效地设计、构建和运行大规模分布式系统。
SRE 的核心职能包括
• 监控和指标 — 建立期望的服务行为，衡量服务的实际行为，并纠正差异。
• 紧急响应 — 注意并有效地响应服务故障，以保持服务符合其 SLA（服务级别协议）。
• 容量规划 — 预测未来需求，并确保服务在适当的位置拥有足够的计算资源来满足该需求。
• 服务启动和关闭 — 以可预测的方式在数据中心为服务部署和移除计算资源，这通常是容量规划的结果。
• 变更管理 — 在保持服务可靠性的同时更改服务的行为。
• 性能 — 与可扩展性、隔离、延迟、吞吐量和效率相关的设计、开发和工程。
SRE 专注于服务的生命周期——从构思和设计，到部署、运营、改进，以及最终的退役。
在服务上线之前，SRE 通过系统设计咨询、开发软件平台和框架以及容量计划、进行发布评审等活动来支持它们。
一旦服务上线，SRE 通过以下方式支持和维护它们
• 测量和监控可用性、延迟和整体系统健康状况。
• 审查计划的系统变更。
• 通过自动化等机制可持续地扩展系统。
• 通过推动改进可靠性和速度的变更来改进系统。
• 进行事件响应和无责事后分析。
一旦服务到达生命周期结束，SRE 会以可预测的方式，通过清晰的消息传递和文档记录将其退役。
成熟的 SRE 团队可能拥有与许多 SRE 职能相关的明确定义的文档体系。如果您管理一个 SRE 团队或打算启动一个团队，本文将帮助您了解您的团队需要编写哪些类型的文档，以及每种类型文档的需求原因，从而使您能够与其他团队项目一起规划和优先考虑文档工作。
SRE 的故事
在讨论 SRE 文档的细微之处之前，让我们先看看一位名叫 Zoë 的新 SRE 的一天一夜。
Zoë 是 Acme 公司旗舰产品 AcmeSale 的 SRE，这是她的第二次随叫随到轮班。她已经完成了作为团队成员的入职流程，在此期间，她观察了同事们随叫随到的情况，并尽可能地做了笔记。现在她要负责寻呼机了。
碰巧的是，寻呼机在凌晨 2:30 响了。警报显示“Ragnarok job flapping”，Zoë 不知道这意味着什么。她翻阅笔记，找到了主仪表板页面的链接。一切看起来都正常。她在 Acme 内网上搜索任何引用 Ragnarok 的文档，在宝贵的几分钟过去后，她找到了该服务的过时设计文档，事实证明该服务是 AcmeSale 的关键依赖项。
幸运的是，设计文档链接到了“Ragnarok Ops”页面，该页面链接到了一个仪表板，其中包含看起来可能有用的图表。其中一个图表显示了看起来令人担忧的流量下降。Ops 页面还引用了一个名为 ragtool 的脚本，该脚本显然可以修复她正在看到的问题，但这是她第一次听说它。此时，她呼叫了备用随叫随到 SRE 寻求帮助，因为他对该服务及其管理工具有多年的经验。不幸的是，她没有得到回应。她查看了电子邮件，发现同事发来一条消息，说他因健康紧急情况而离线一小时。经过片刻的内心挣扎，她给她的技术主管打了电话，但电话转到了语音信箱。看来她必须独自解决这个问题。
在搜索更多信息以了解这个神秘的 ragtool 脚本后，她找到了一份文档，其中包含对其命令行选项的单行描述，该文档还告诉她可以在哪里找到该脚本。她运行了 ragtool —restart 并祈祷好运。没有任何变化，事实上流量甚至下降得更多。她疯狂地阅读更多命令行选项，但不确定它们是弊大于利。最后，她得出结论，ragtool —rebalance e—dc=atlanta 可能会有所帮助，因为另一个图表表明亚特兰大数据中心遇到了更多麻烦。果然，流量图上的线开始向上爬升，她认为自己已经脱离困境。MTTR（平均修复时间）为 45 分钟。
第二天，Zoë 与她的团队进行了关于该事件的事后分析讨论。他们正在进行这次讨论，因为该事件是一次重大中断，造成了收入损失，他们的经理一直在要求他们做更多的事后分析。她问团队他们会如何以不同的方式处理这种情况，她听到了三种不同的方法。似乎没有标准的故障排除流程。她的同事们也承认，“flapping”警报的命名很差，并且故障是产品中一个众所周知的 bug 造成的，但该 bug 一直不是开发团队的优先事项。
最后，她的技术主管 Steve 问道：“你使用了哪个版本的 ragtool？”然后指出她使用的版本非常旧。一周前发布了一个新版本，其中包含描述其所有新功能的新文档，甚至解释了如何修复“Ragnarok job flapping”问题。它可能会将 MTTR 缩短到五分钟。
大约一半的团队对新版本的 ragtool 的存在感到惊讶，而另一半人不知何故熟悉新版本及其用户指南。最新的脚本和文档都位于 Steve 的主目录下的 bin/ 文件夹中，当然。Zoë 将此记在笔记中以供将来参考，虔诚地希望她能顺利度过这次轮班，不再出现警报。她想知道她的技术主管或其他人是否会跟进事后分析讨论期间发现的问题，或者未来的 SRE 是否注定要重复同样的痛苦的随叫随到体验。
当天晚些时候，Zoë 参加了一个 SRE 入职培训，SRE 团队与一个产品开发团队会面，讨论接管他们的服务。Steve 主持了会议，就服务的运营程序和当前可靠性问题提出了一些尖锐的问题，并要求开发团队在 SRE 团队接管之前进行一些运营和功能更改。Zoë 已经参加过几次这样的会议，这些会议由 Steve 或另一位资深 SRE 主持。她意识到，提出的问题和分配给开发人员的操作似乎差异很大，这取决于谁主持会议以及 SRE 团队过去一周处理过的产品故障类型。
她隐约希望团队拥有更一致的标准和程序，但不太清楚如何实现该目标。后来，她听到两位开发人员在咖啡机旁开玩笑说，许多问题似乎与携带寻呼机无关，他们不知道这些问题从何而来。她希望产品开发团队能够理解 SRE 所做的工作远不止携带寻呼机。然而，回到办公桌后，Zoë 发现有几个紧急工单需要解决，因此她再也没有跟进这些想法。
幸运的是，这个故事中的所有角色和情节都是虚构的。尽管如此，请考虑一下故事的任何部分是否与您的任何现实生活经历相似。这个虚构团队的困境的解决方案是显而易见的，下一节将扩展这个解决方案。
文档的重要性
在 SRE 团队存在的早期阶段，组织在很大程度上依赖于团队中高技能个人的表现。团队将重要的运营概念和原则作为“部落知识”的精髓保存下来，并通过口头传达给新团队成员。如果这些概念和原则没有被编纂和记录下来，它们通常需要通过反复试验——痛苦地——重新学习。有时，团队成员按照其前辈在遥远的过去定义的严格步骤顺序执行操作程序，而不理解最初规定这些步骤的原因。如果允许这种情况继续下去，随着团队规模扩大以应对新的挑战，流程最终会变得支离破碎并趋于退化。
SRE 团队可以通过创建高质量的文档来防止这种流程衰退，这些文档为这些团队扩展规模并采用有原则的方法来管理新的和不熟悉的服务奠定了基础。这些文档以易于发现、搜索和维护的形式捕获部落知识。通过系统且计划周全的入职和教育计划对新团队成员进行培训。这些是成熟 SRE 团队的标志。
本文的其余部分描述了 SRE 在其支持的服务的生命周期中创建的各种类型的文档。
新服务入职文档
SRE 进行 PRR（生产就绪审查），以确保服务符合公认的运营就绪标准，并且服务所有者拥有他们需要的指导，以利用 SRE 关于运行大型系统的知识。
服务必须在首次发布到生产环境之前通过此审查流程。（在此阶段，服务没有 SRE 支持；产品开发团队支持该服务。）发布前 PRR 的目标只是确保服务在发布时符合某些最低可靠性标准。
后续 PRR 可以在 SRE 接管服务之前执行，这可能在首次发布后很久才会发生。例如，当 SRE 团队决定加入一项新服务时，团队会对新服务的生产状态和实践进行彻底审查。目标是从可靠性和运营可持续性的角度改进正在加入的服务，并为 SRE 提供有关服务运营的初步知识。
与首次发布时进行 PRR 相比，在服务接管之前进行 PRR 的 SRE 可能会提出更全面的问题集，并应用更高的可靠性和运营便利性标准。他们可能会有意使发布时 PRR 比服务接管 PRR “更轻”，以避免不必要地减慢开发团队的速度。
在 Zoë 的 SRE 故事中，她的团队没有标准化的 PRR 流程或清单，这意味着他们可能会在服务接管期间遗漏提出重要问题。因此，他们在管理一项新服务时，可能会遇到许多容易预见且可以在 SRE 负责运行服务之前解决的问题。
SRE PRR/接管需要创建 PRR 模板和流程文档，该文档描述 SRE 团队将如何与新服务互动，以及 SRE 团队将如何使用 PRR 模板。接管时使用的模板可能比首次发布时使用的模板更全面。
PRR 模板涵盖了几个领域，并确保回答了关于每个领域的关键问题。表 1 列出了模板涵盖的一些领域和相关问题。
| 领域 |
问题 |
| 架构和依赖关系 |
从用户到前端到后端，您的请求流程是什么？ 是否存在具有不同延迟要求的不同类型的请求？ |
| 容量规划 |
您预计在发布期间和发布后会有多少流量和增长率？ 您是否已获得支持您的流量所需的所有计算资源？ |
| 故障模式 |
您的设计中是否存在任何单点故障？ 您如何缓解依赖项的不可用性？ |
| 流程和自动化 |
是否需要任何手动流程来保持服务运行？ |
| 外部依赖项 |
服务或发布依赖于哪些第三方代码、数据、服务或事件？ 是否有任何合作伙伴依赖于您的服务？如果是这样，他们是否需要收到您的发布通知？ |
表 1 PRR 模板区域示例
流程文档还应确定 SRE 团队应要求产品开发团队提供的文档类型，作为接管的先决条件。例如，他们可能会要求开发团队为标准问题创建初始剧本条目。
除了这些入职文档外，SRE 组织还需要创建概述文档，以向产品开发团队以通用术语解释 SRE 的角色和职责。这有助于正确设定他们的期望。第一份此类文档将解释什么是 SRE，涵盖本文开头列出的所有主题，包括核心职能、服务生命周期以及支持/维护职责。本文档的主要目标是确保开发团队不会将 SRE 等同于 Ops 团队，或认为寻呼机响应是他们的唯一职能。如之前的 SRE 故事所示，当开发人员在将服务移交给 SRE 之前没有完全理解 SRE 的工作时，可能会导致沟通不畅和误解。
此外，参与模型文档更进一步地设定期望，通过解释 SRE 团队在服务接管期间和之后将如何与开发团队互动。此文档中涵盖的主题包括
• 服务接管标准和 PRR 流程。
• SLO 协商流程和错误预算。
• 新发布标准和发布冻结策略（如果适用）。
• 来自 SRE 团队的服务状态报告的内容和频率。
• SRE 人员配置要求。
• 功能路线图规划流程以及可靠性功能（由 SRE 团队请求）与新产品功能的优先级。
服务运行文档
SRE 团队依赖于执行生产服务的核心运营文档包括服务概述、剧本和程序、事后分析、策略和 SLA。（注意：本节出现在《寻求 SRE》1的“更好地编写文档”章节中。）
服务概述
服务概述对于 SRE 理解他们支持的服务至关重要。SRE 需要了解系统架构、组件和依赖项以及服务联系人和所有者。服务概述是开发团队和 SRE 团队之间的协作成果，旨在指导和优先考虑 SRE 的参与，并发现需要进一步调查的领域。这些概述通常是 PRR 流程的输出，并且应随着服务的更改（例如，新的依赖项）而更新。
基本服务概述为 SRE 提供了足够的关于服务的信息以进行深入挖掘。完整的服务概述提供了关于服务及其如何与周围世界交互的详尽描述，以及指向仪表板、指标和 SRE 解决意外问题所需的相关信息的链接。
剧本
也称为运行手册，这个典型的运营文档让随叫随到的工程师能够响应服务监控生成的警报。例如，如果 Zoë 的团队有一个剧本，解释了“Ragnarok job flapping”警报的含义并告诉她该怎么做，则该事件可以在几分钟内解决。剧本减少了缓解事件所需的时间，并提供了指向控制台和程序的有用链接。
剧本包含验证、故障排除和从网络监控流程生成的每个警报的升级说明。剧本通常与监控系统生成的警报名称匹配。它们包含需要测试和审查准确性的命令和步骤。当新的故障排除流程可用以及发现新的故障模式或添加依赖项时，它们通常需要更新。
剧本并非警报独有，还可以包括用于推送发布、监控和故障排除的生产程序。生产程序的其他示例包括服务启动和关闭、服务维护以及紧急/升级。
事后分析
SRE 与大规模、复杂、分布式系统合作，他们还通过新功能和新系统的添加来增强服务。因此，鉴于 SRE 的规模和变更速度，事件和中断是不可避免的。事后分析是 SRE 的重要工具，代表了其从事件中学习的正式流程。在假设的 SRE 故事中，Zoë 的团队没有正式的事后分析程序或模板，因此，也没有正式的流程来捕获从事件中学习到的知识并防止其再次发生，因此他们注定要重复相同的问题。
SRE 团队需要创建一个标准化的事后分析文档模板，其中包含捕获关于中断的所有重要信息的部分。理想情况下，此模板将以一种可以被数据分析工具轻松解析的格式构建，这些工具使用事后分析作为数据源来报告中断趋势。从该模板派生的每个事后分析都描述了生产中断或寻呼事件，包括（至少）
• 时间线。
• 用户影响描述。
• 根本原因。
• 行动项/经验教训。
事后分析由经历中断的小组的成员编写，最好是参与其中并可以负责跟进的人员。事后分析需要以无责的方式编写。它应包括理解所发生的事情所需的信息，以及一份行动项清单，这些行动项将大大降低再次发生的可能性，减少影响，和/或使恢复更加直接。（有关编写事后分析的指南，请参阅《站点可靠性工程》2中描述的事后分析模板。）
策略
策略文档规定了生产的特定技术和非技术策略。技术策略可以应用于生产变更日志记录、日志保留、内部服务命名（工程师在实施服务时应采用的命名约定）以及紧急凭据的使用和访问等领域。
策略也可以应用于流程。升级策略帮助工程师将生产问题分类为紧急或非紧急问题，并为每个类别提供关于适当操作的建议；随叫随到期望策略概述了团队的结构和团队成员的职责。
服务级别协议
SLA 是与客户就服务承诺提供的性能以及如果未履行该义务将采取的措施达成的正式协议。SRE 团队记录其服务在可用性和延迟方面的 SLA，并监控相对于 SLA 的服务性能。
记录和发布 SLA，并严格测量最终用户体验并将其与 SLA 进行比较，使 SRE 团队能够在保持良好用户体验的同时更快地进行创新。运行具有明确定义的 SLA 的 SRE 将更快地检测到中断，从而更快地解决它们。良好的 SLA 还可以减少 SRE 和 SWE（软件工程师）团队之间的摩擦，因为这些团队可以客观地协商目标和结果，并避免对风险进行主观讨论。
请注意，拥有外部具有法律约束力的协议可能不适用于大多数 SRE 团队。在这些情况下，SRE 团队可以使用一组 SLO（服务级别目标）。SLO 是对服务在可用性或延迟等单个指标方面期望性能的定义。
生产产品文档
SRE 团队的目标是将 50% 的时间用于项目工作，开发软件以自动化人工工作或提高托管服务的可靠性。本节描述与 SRE 开发的产品和工具相关的文档。
这些文档很重要，因为它们使用户能够了解产品是否适合他们采用、如何入门以及如何获得支持。它们还提供一致的用户体验并促进产品采用。
关于页面
关于页面帮助 SRE 和产品开发工程师了解产品或工具是什么、它的作用以及他们是否应该使用它。
概念指南
概念指南或词汇表定义了产品独有的所有术语。定义术语有助于保持文档以及 UI、API 或 CLI（命令行界面）元素的一致性。
快速入门指南
快速入门指南的目标是让工程师以最小的延迟启动并运行。它对想要试用新产品的用户很有帮助。
代码实验室
工程师可以使用这些教程——结合了解释、示例代码和代码练习——来快速掌握产品。代码实验室还可以提供深入的场景，逐步引导工程师完成一系列关键任务。这些教程通常比快速入门指南更长。如果它们相互作用，它们可以涵盖多个产品或工具。
操作指南
此类文档适用于需要了解如何使用产品完成特定目标的用户。操作指南帮助用户完成重要的特定任务，并且它们通常基于程序。
常见问题解答
常见问题解答页面回答常见问题，涵盖用户应注意的注意事项，并将用户指向参考文档和站点上的其他页面以获取更多信息。
支持
支持页面标识了工程师在遇到问题时如何获得帮助。它还包括升级流程、故障排除信息、群组链接、仪表板和 SLO 以及随叫随到信息。
API 参考
本指南提供了对函数、类和方法的描述，通常带有最少的叙述或读者指导。此文档通常从代码注释生成，有时由技术作家编写。
开发人员指南
工程师使用本指南了解如何针对产品的 API 进行编程。当 SRE 创建向开发人员公开 API 的产品时，此类指南是必需的，从而可以创建调用彼此 API 以完成更复杂任务的复合工具。
服务状态报告文档
本节描述了 SRE 团队生成的用于沟通他们支持的服务的状态的文档。
季度服务审查
关于服务状态的信息有两种形式：SRE 负责人审查并与 SRE 组织共享的季度报告，以及向产品开发负责人和团队进行的演示。
季度报告（和演示）的目标是涵盖“服务状态”审查，包括关于性能、可持续性、风险和整体生产健康状况的详细信息。
SRE 负责人对季度报告感兴趣，因为它们提供了以下方面的可见性
• 支持负担（随叫随到、工单、事后分析）。SRE 负责人知道，当支持负担超过 SRE 团队资源的 50% 时，他们必须做出响应并更改团队的优先级。目标是在这种情况开始朝着错误的方向发展时发出早期警告。
• SLA 的性能。SRE 负责人通常想知道是否错过了 SLA，或者生态系统中是否存在不健康的组件，使产品客户处于危险之中。
• 风险。SRE 负责人想知道 SRE 看到的在实现产品和业务目标方面存在哪些风险。
季度报告还为 SRE 团队提供了以下机会
• 突出 SRE 正在为产品开发团队提供的益处，以及 SRE 团队的工作。
• 请求优先解决阻碍 SRE 团队的问题（可持续性）。
• 请求对 SRE 团队的重点和优先事项的反馈。
• 突出团队正在做出的更广泛的贡献。
生产最佳实践审查
通过此审查，SRE 团队能够更好地采用生产最佳实践，并达到非常稳定的状态，从而减少他们在运营上花费的时间。SRE 团队通过提供诸如团队网站和章程、随叫随到健康状况详细信息、项目与中断、SLO、容量规划等详细信息来为这些审查做准备。
最佳实践审查帮助 SRE 团队根据 SRE 组织的其他部分进行自我校准，并在随叫随到健康状况、项目与中断、SLO 和容量规划等关键运营领域进行改进。
SRE 团队运行文档
SRE 团队需要拥有一套有凝聚力、可靠且易于发现的文档，才能作为一个团队有效地运作。
团队站点
创建团队站点非常重要，因为它为关于 SRE 团队及其项目的信息和文档提供了一个焦点。例如，在 Google，许多 SRE 团队使用 g3doc（Google 的内部文档平台，文档与相关代码一起位于源代码中），但一些团队使用 Google Sites 和 g3doc 的组合，其中 g3doc 页面与代码/实现细节紧密相关。
团队章程
SRE 团队应维护已发布的章程，其中解释了团队的理由并记录了其当前的主要参与。章程有助于确立团队身份、主要目标以及相对于组织其他部分的角色。
章程通常包括以下要素
• 对团队运作空间的概括性解释。这包括团队参与的服务类型（以及方式）、相关系统和示例。
• 对团队管理的排名前两到三位的服务的简短描述。本节还重点介绍了使用的关键技术以及运行这些技术的挑战、SRE 参与的好处以及 SRE 的工作。
• 团队的关键原则和价值观。
• 团队站点和文档的链接。
团队还应发布愿景声明（对团队希望在长期内实现的愿望描述）和跨多个季度的路线图。
新 SRE 入职文档
SRE 团队在新 SRE 的培训材料和流程上投入资金，因为培训可以加快新员工加入生产环境的速度。SRE 团队还可以从新成员尽快获得加入随叫随到行列所需的技能中获益。正如 Zoë 的故事中所见，在缺乏全面培训的情况下，随叫随到的 SRE 可能会在危机期间陷入困境，从而将潜在的轻微事件变成重大中断。
许多 SRE 团队使用随叫随到培训清单。随叫随到清单通常涵盖团队成员应充分理解的所有高级领域，每个领域下都有小节。高级领域的示例包括生产概念、前端和后端堆栈、自动化和工具以及监控和日志。清单还可以包括关于为随叫随到做准备的说明以及随叫随到时需要完成的任务。
SRE 还使用角色扮演培训演习（在 Google 内部称为厄运之轮） 作为培训团队成员的教育工具。厄运之轮 演习向团队展示中断情景，并提供一组数据和信号，假设的随叫随到 SRE 需要使用这些数据和信号作为输入来解决中断。团队成员轮流扮演随叫随到工程师的角色，以磨练紧急情况缓解和系统调试技能。厄运之轮演习应测试单个 SRE 知道在哪里找到与故障排除和解决手头中断最相关的文档的能力。
仓库管理
SRE 团队的信息可能分散在许多站点、本地团队知识和 Google Drive 文件夹中，这使得查找正确和相关的信息变得困难。正如前面 SRE 示例中提到的那样，关键的运维工具及其用户手册对 Zoë（值班 SRE）不可用，因为它们隐藏在她技术主管的主目录中，她无法找到它们大大延长了服务中断时间。为了消除此类故障，定义所有信息的一致结构并确保团队成员知道在哪里存储、查找和维护信息非常重要。一致的结构将帮助团队成员快速找到信息。新团队成员可以更快地上手，值班和当班工程师可以更快地解决问题。
以下是创建和管理团队文档存储库的一些指南
• 确定相关的利益干系人并进行简短的访谈，以识别所有需求。
• 尽可能找到更多的文档，并对内容进行差距分析。
• 为站点设置基本结构，以便可以在正确的位置创建新文档。
• 将相关的现有文档移植到新位置。
• 创建监控和报告结构，以跟踪迁移进度。
• 归档和拆除旧文档。
• 定期执行检查，以验证是否保持了一致性/质量。
• 验证常用的搜索词是否在搜索结果的顶部附近显示正确的文档。
• 使用 Google Analytics 等信号来衡量使用情况。
关于存储库维护的注意事项：定期审查和更新文档非常重要。所有者的姓名以及上次审查日期应可见——所有这些信息都有助于文档的可信度。在 Zoë 的故事中，她找到了并使用了关键运维工具的过时文档，因此错失了快速解决事件的机会，反而经历了重大中断。如果文档不能被信任是准确和最新的，这可能会降低 SRE 的效率，直接影响他们管理服务的可靠性。
存储库可用性
SRE 团队必须确保即使在导致标准存储库不可用的中断期间，文档也可用。在 Google，SRE 拥有关键文档的个人副本。此副本存储在加密的紧凑型存储设备或类似的可拆卸但安全的物理介质上，所有值班 SRE 都随身携带。
服务退役文档
一旦服务达到生命周期结束，SRE 会以可预测的方式将其退役。本节提供服务弃用直至最终退役的消息传递和文档指南。
重要的是提前向当前服务用户宣布退役，并向他们提供时间表和步骤顺序。您的公告应解释何时不再接受新用户，如何处理现有和新发现的错误，以及服务何时完全停止运行。清楚说明重要日期以及何时减少对服务的 SRE 支持，并在时间表进展过程中发送中期公告。
仅发送电子邮件是不够的，您还必须更新您的主要文档页面、剧本和代码实验室。此外，如果适用，请注释头文件。在文档（除了电子邮件）中捕获公告的详细信息，以便用户轻松指向该文档。保持电子邮件尽可能简短，同时捕捉要点。在文档中提供更多详细信息，例如退役服务的业务动机、用户在迁移到替代服务时可以利用哪些工具，以及迁移期间可以获得哪些帮助。您还应该为项目创建一个 FAQ 页面，随着时间的推移，随着您收到用户的新问题，不断扩充该页面。
技术文档工程师的角色
技术文档工程师提供各种服务，使 SRE 能够高效且富有成效。这些服务远远超出根据 SRE 团队收到的需求编写单个文档的范围。
以下是为技术文档工程师提供的与 SRE 团队合作的最佳实践指南。
• 技术文档工程师应与 SRE 合作，为运行服务提供运维文档，并为 SRE 产品和功能提供产品文档。
• 他们可以创建和更新文档存储库，重组和重新组织存储库以符合用户需求，并改进单个文档，作为整体存储库管理工作的一部分。
• 文档工程师应提供咨询，以评估、协助和解决文档和信息管理需求。这包括进行文档评估以收集需求，增强工程师创建的文档和站点，以及就与文档创建、组织、重新设计、可查找性和维护相关的事项向团队提供建议。
• 文档工程师应评估和改进文档工具，为 SRE 提供最佳解决方案。
模板
技术文档工程师还提供模板，使 SRE 文档更易于创建和使用。模板执行以下操作
• 通过提供清晰的结构，使作者可以轻松创建文档，以便工程师可以快速使用相关信息填充它。
• 通过包含所有必需文档部分的章节，确保文档完整。
• 使读者可以轻松快速地了解文档的主题、它可能包含的信息类型以及它的组织方式。
站点可靠性工程 包含几个文档模板的示例。在本节中，我们提供更多示例，以演示模板如何为工程师填充内容提供结构和指导。
服务概述
概述
它是什么？它做什么？从高层次描述为客户（最终用户、组件等）提供的功能。
架构
解释架构的工作原理。描述组件之间的数据流。考虑添加一个包含关键依赖项以及请求和数据流的系统图。
客户和依赖项
列出任何依赖于它的上游客户（由其他团队拥有）以及它所依赖的下游服务（由其他团队拥有）。（这些也可以在系统图中显示。）
代码和配置
解释生产环境设置。它在哪里运行？列出二进制文件名、作业、数据中心和配置文件设置，或指向这些文件的规范位置。如果相关，还请提供代码位置和构建信息。
列出并描述操作此产品或服务所需的配置文件、更改和端口。
解决以下问题：为此产品或服务修改了哪些配置文件？如何处理配置？
进程
解决以下问题：必须运行哪些守护程序和其他进程才能执行服务？创建了哪些控制脚本来管理此服务？
输出
列出并描述组件创建的或组件内的日志文件以及针对它运行的监控。解决以下问题：组件生成哪些日志文件？每个文件包含什么？您对检查这些日志文件有什么建议？必须监控组件的哪些方面以确保可靠的服务？
仪表板和工具
链接到相关的仪表板和工具。
容量
列出单个实例的容量；每个数据中心；全局：QPS、带宽和延迟数字。
SLA
给出可用性目标。
常用程序
添加程序链接。这些可能包括负载测试、更新/推送/标志翻转等。链接到警报剧本中的警报文档。
参考
链接到组件或相关组件的设计文档，通常由开发团队编写，以及其他相关信息。
剧本
标题
标题应为警报的名称（例如，Generic Alert_AlertTooGeneric）。
概述
解决以下问题：此警报意味着什么？它是寻呼警报还是仅电子邮件警报？哪些因素导致了警报？服务的哪些部分受到影响？还有哪些警报伴随此警报？应该通知谁？
警报严重程度
指出警报严重程度（电子邮件或寻呼）的原因以及警报条件对系统或服务的影响。
验证
提供关于如何验证条件是否正在进行的具体说明。
故障排除
列出并描述调试技术和相关信息来源。包括相关仪表板的链接。包括警告。解决以下问题：此警报触发时日志中显示什么？有哪些可用的调试处理程序？有哪些有用的脚本或命令？它们生成什么样的输出？警报解决后还需要完成哪些其他任务？
解决方案
列出并描述解决此警报的可能解决方案。解决以下问题：我该如何修复问题并停止此警报？应该运行哪些命令来重置事物？如果此警报是由于用户行为而发生的，应该联系谁？谁在调试此问题方面有专长？
升级
列出并描述升级路径。确定要通知谁（个人或团队）以及何时通知。如果不需要升级，请注明。
相关链接
提供指向相关警报、程序和概述文档的链接。
季度服务报告
引言
描述团队负责的服务。
容量计划
包括
过去六到八个季度的实际服务需求，以与服务最相关的指标表示（例如，QPS 或每日活跃用户）。
未来八个季度的当前需求预测。
足以满足所需冗余级别的预测需求的容量计划——突出容量计划的不足和/或风险。
容量计划必须包含与过去两到四个季度预测的叠加，以便读者可以评估预测的稳定性和随时间推移的准确性。
SLA 性能 / 可用性
所有 SRE 支持的服务都需要有书面的 SLA，并至少每季度评估其相对于 SLA 的性能。
SLA 部分必须包含对服务主要组件的季度性能与 SLA 进行的衡量，以及指向团队书面 SLA 的链接。
贡献事件（可选）
列出本季度排名前三到五位的事件或中断。
成就（可选）
列出本季度的主要成就。
SLA 修改（推荐）
最近对 SLA 的修改。
服务详情（推荐）
可能包括服务增长、延迟统计信息等。
团队信息（可选）
可能包括团队人员配备和状态、项目、值班统计信息。
数据来源（必需）
描述用于推导可用性数字的数据来源、计算方法，并提供指向相关仪表板的链接。
团队章程
我们是谁
添加一句话来描述技术环境（约 1 行）、团队的客户和产品，以及团队的 SRE 参与范围或专业知识。
支持的服务
描述您的团队支持的（一组）服务，以进一步定义您团队的范围。
我们如何分配时间
确定工作范围将有助于定义您的路线图，了解如何在长期内实现和维持您的目标。
团队价值观
以清晰的方式沟通您的团队价值观。它们将影响团队成员之间的互动以及其他团队对您的团队的看法。
结论
无论您是 SRE、SRE 经理还是技术文档工程师，您现在都了解了文档对于运作良好的 SRE 团队的关键重要性。良好的文档使 SRE 团队能够扩展规模，并采用有原则的方法来管理新的和现有的服务。
参考
1. Blank-Edelman, D. N. 2018. 寻求 SRE：关于大规模运行生产系统的对话. O'Reilly Media.
2. Murphy, N., Beyer, B., Jones, C., Petoff, J. 2016. 站点可靠性工程：Google 如何运行生产系统。O'Reilly Media.
相关文章
服务可用性的计算
您的可用性与您的依赖项的总和一样。
Ben Treynor, Mike Dahlin, Vivek Rau, Betsy Beyer
https://queue.org.cn/detail.cfm?id=3096459
弹性工程：学会拥抱失败
与 Jesse Robbins、Kripa Krishnan、John Allspaw 和 Tom Limoncelli 的讨论
https://queue.org.cn/detail.cfm?id=2371297
全球可靠的 Cron
...或者我如何停止担忧并学会热爱时间
Štěpán Davidovič 和 Kavita Guliani，Google
https://queue.org.cn/detail.cfm?id=2745840
Shylaja Nukala 是 Google 站点可靠性工程的技术文档主管。她领导 SRE、云和 Google 工程师的文档、信息管理和精选培训工作。Shylaja 拥有罗格斯大学传播学博士学位。
Vivek Rau 是 Google 的站点可靠性工程师，致力于 CRE（客户可靠性工程）。CRE 团队向客户讲授核心 SRE 原则，使他们能够在 Google Cloud Platform 上构建和运营高度可靠的产品。Vivek 拥有 IIT-马德拉斯计算机科学学士学位。
版权所有 © 2018，所有者/作者持有。出版权已授权给 。
最初发表于 Queue vol. 16, no. 4—
在 数字图书馆 中评论本文
更多相关文章
Taylor Savage - Web 组件化
在当今的软件工程中，没有哪项任务能像 Web 开发那样艰巨。Web 应用程序的典型规范可能如下：应用程序必须跨各种浏览器工作。它必须以 60 fps 的速度运行动画。它必须立即响应触摸。它必须符合一组特定的设计原则和规范。它必须在几乎所有可以想象到的屏幕尺寸上工作，从电视和 30 英寸显示器到手机和手表表面。它必须经过精心设计，并且长期可维护。
Arie van Deursen - 超越页面对象：使用状态对象测试 Web 应用程序
Web 应用程序的端到端测试通常涉及通过 Selenium WebDriver 等框架与 Web 页面进行棘手的交互。隐藏此类 Web 页面复杂性的推荐方法是使用页面对象，但首先要回答一些问题：在测试 Web 应用程序时，应该创建哪些页面对象？页面对象中应该包含哪些操作？给定页面对象，应该指定哪些测试场景？
Rich Harris - 消除入门障碍
一场战争正在 Web 开发领域中进行。一方是工具制造者和工具用户的先锋，他们以摧毁糟糕的旧观念（在这个环境中，“旧”意味着任何在一个多月前在 Hacker News 上首次亮相的东西）以及关于转译器等的热烈辩论为乐。
Alex Liu - JavaScript 和 Netflix 用户界面
自问世以来的二十年中，JavaScript 已成为 Web 事实上的官方语言。在运行时环境的数量方面，JavaScript 胜过所有其他语言。如今市场上几乎每一种消费硬件设备都以某种方式支持该语言。虽然这最常见的方式是通过集成 Web 浏览器应用程序来完成的，但现在许多设备也以本机方式支持 Web 视图，作为操作系统 UI（用户界面）的一部分。
© 保留所有权利。