Checkout服务金丝雀发行

1）为什么需要操作文档

• 将口头知识转化为可重复的程序；
• 指定责任界限和升级点；
• 作为合规和安全证据的来源；
• 加快爬山速度，降低"狭窄颈部"的风险。

2）文件分类法（什么）

政策（政策）：意图和框架（"什么以及为什么"）。示例：事件管理政策。
标准（标准）：强制性最低要求（"多少"）。示例：TLS证书的更新时间。
SOP/Procedure（标准操作程序）：连续步骤（"as"）。示例：发行带有金丝雀拆分的版本。

Runbook： 用于典型事件（Alert/Operation）的分步说明。示例："5xx API成长为动作算法。"

剧本：一组具有变体和叉子的脚本解决方案。示例："支付提供商的问题"。
KB（知识库）：答桉,常见问题,工具说明。
Checklist：操作前必备项目的简要列表。
记录/事件：执行步骤的日志、截图/记录/签名。

3）良好的文档原则

单一真相来源（SSOT）。文件没有重复；喷洒意味着过时。
Docs-as-Code.我们存储在Git中，通过代码评论，版本和诽谤-可见。
Actionable-first.一开始是一张简短的卡片：何时运行，谁是所有者，该怎么做，完成标准。
原子性和目标性。一个文档是一个任务/过程。
可更新性。更新的明确所有者和SLA（例如季度）。
可观察性。嵌入了对dashbords/alerta/度量的引用。
按设计安全。敏感性分类，掩盖秘密，访问控制。

4）文档生命周期（政府）

1.启动：申请/提要→文件类型→所有者。
2.草稿：模板、最少示例、标准参考和SLO。
3.评论：技术（SRE/平台/安全），程序（流程经理）。
4.发布：在主分支中，标记版本/日期，状态分配（active/experimental/deprecated）。
5.培训/沟通：更改公告，短期培训/演示。
6.回顾：根据事件/演习的结果进行编辑。
7.审核和归档：归档中旧版的不可变足迹（谁/何时更改）。

5） SOP/Runbook结构（最低限度）

1.卡：名称,ID,版本/日期,所有者,负责角色,相关政策/标准。
2.何时应用：启动条件（Alert/事件/工作窗口）。
3.准备：权利/工具/数据，风险评估，通信。
4.步骤：编号，带有命令/屏幕截图/预期结果。
5.成功/回滚标准：明确的SLI/SLO阈值。
6.升级：谁，何时以及如何（频道，电话，提供商）。
7.安全/合规性：敏感数据，禁令，活动记录。
8.后期行动：关闭滴答声，更新状态，收集证据。
9.更改历史（changelog）。

6）设计风格和规则

清晰而简短：1个步骤-1个动作-1个结果。
当务之急："执行……"，"检查……"，"滚动……"。
截图/命令：靠近步骤；命令-可复制的块；预期的输出。

变异性： "如果A →步骤X，如果B →步骤Y。"

队列：在哪里-指定区域/提供者/tenant。
本地化：关键文件-至少2种语言；指定翻译状态。
标签和搜索：服务,组件,提供商,事件类型,SLO,版本。

7） Docs-as-Code和工具

存储：git（主要/壮举/bugfix），公关评论，要求检查。
格式：Markdown/AsciiDoc；PlantUML/美人鱼图表；JSON/YAML方案。
发布：静态站点（Docusaurus/MkDocs）+搜索。
验证：CI-lint，参考测试，拼写，代码块验证器。
集成：ChatOps命令"/runbook open X"，在警报中显示最新版本。
链接：CMDB/服务目录 ↔文档↔仪表板。

8）访问控制和分类

Классы: Public / Internal / Confidential / Restricted.

分离：公共指令（共享状态）vs私人（密钥、命令、网络图表）。
秘密：禁止在文本中；使用秘密存储和播放器。
审计：敏感SOP的阅读/更改日志。

9）与事件和发布的通信

在每个警报中，都引用了相关的运行手册。
在每个事件中，都引用了使用的SOP和标记检查。
RCA之后-将文档更新为CAPA操作。
发行前-checklist：回滚准备、降级标志、提供商联系人。

10）最低强制性套装（MVP基座套件）

事件管理和升级政策（SEV/P级别，时间）。
监控标准和警报策略（burn rate，法定人数）。
SOP：释放/回滚（金丝雀/蓝绿色），DB迁移（expand/contract）。
运行手册："高错误率"，"增长p99"，"支付成功率下降"，"TLS/DNS问题"。
外部提供商的剧本（付款/KYC/CDN）：联系人，限制，后卫。
秘密和访问管理策略。
RCA和Post-mortem模板。
服务所有者表（RACI）和行车记录卡。

11）文档质量指标（SLO文档）

Coverage：使用SOP/Runbook的关键路径的百分比。
Freshness：文档比例为新鲜的N天（例如90）。
可用性：根据运行手册关闭的事件百分比没有升级。
Findability：搜索所需文档的时间中位数（按调查/逻辑）。
Defect rate： 评论数/100份文件。
Adoption：正确引用运行簿的Alert分数。
合规性事件率：所附证据的任务百分比。

12）支票单

SOP创建支票清单

• 已确定所有者和目标受众。
• 有发射条件和停止标准。
• 步骤可以复制,由其他工程师验证。
• 嵌入了指向dashbords/alerta/工具的链接。
• 没有秘密；有播放器并链接到vault。
• 描述了回滚和升级。
• 添加了"行动后"支票单。
• 版本、日期、changelog。

Review的支票清单

• 该文档对应于分类法（不混合政策和步骤）。
• 语言简单，强制性，没有歧义。
• 在"干运行"/stadge中测试团队。
• 指明了风险和控制点。
• 可用性（内部/限制）是正确的。
• 在CI中通过了林特/验证器。

13）本地化、版本和可用性

版本：'MAJOR。MINOR.PATCH',MAJOR打破了流程兼容性。
语言：标记"源"语言和翻译状态（up-to-date/needs review）。
外形规格：手机/夜间通话显示、IC打印卡。

14） Doc自动化（来自实践）

从CLI模板生成SOP框架（"doc new sop -service=payments"）。
按服务标签自动插入指向最新行车记录的链接。
过期文件提醒机器人（freshness SLA）。
在一段时间内导出Evidence软件包（PDF/ZIP）进行审核。
将事件字幕与解决方桉中使用的文档版本关联。

15）安全和合规性

强制性部分"风险"和"控制措施"。
将事件存储在带有签名/哈希的不变档案中。
绑定到法规遵从性（例如,通知/撤销时间）、显式合规性所有者。

16）反模式

"Vicky迷宫"没有所有者和更新日期。
与团队混合的政客-没有人会发现要执行什么。
没有上下文的文档（没有SLO，dashbords，升级）。
带有秘密的屏幕截图或"单击此处"指令，没有CLI替代方案。
"一位大师知道如何"是部落知识，没有固定。
存档PDF作为唯一的版本-不编辑，不搜索。

17）模板（片段）

SOP帽子（示例）

SOP-ID: OPS-REL-001

18）嵌入日常工作

每周文件圈：审查1-2份文件、主流化、交流经验。
游戏日：模拟中的SOP/Runbook现实检查。
Onbording：新手路线通过一组强制性文档+短量表。
码头债务：优先级改进的逆向（impact × effort）。

19）结果

操作文档不是存档,而是工作工具。当它作为代码进行维护时，拥有所有者，新鲜度度量标准并嵌入事件，发布和培训中，组织变得可预测：错误更少，反应更快，可以理解的责任和审计准备。简短地写作，定期更新，自动化例程-文档将开始节省时间和金钱。