writing-runbooks

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing runbooks

编写Runbook

REQUIRED BACKGROUND: the

technical-writing

skill (hard rules, truth rules, style).

必备背景知识：

technical-writing

技能（硬性规则、真实性规则、风格规范）。

Overview

概述

A runbook is read by someone in a hurry, often mid-incident. Every rule here serves that reader: order, one action per step, copy-pasteable commands, and danger marked where the eye already is.

Write from a real run: every step one actually taken, every failure named one that actually happened. A procedure imagined at the desk is a draft, not a runbook.

Runbook是供人们在紧急情况下（通常是事件发生过程中）阅读的文档。此处的每一条规则都是为这类读者设计的：有序的步骤、每步一个操作、可直接复制粘贴的命令，以及在显眼位置标记危险提示。

基于实际执行流程撰写：每一步都是实际执行过的操作，每一个故障都是真实发生过的问题。仅在办公桌前构想的流程只是草稿，不能算作Runbook。

When to invoke, and not

适用场景与排除场景

Invoke for anything a person will execute: runbooks, setup and release procedures, troubleshooting entries, operational checklists, and the operator-facing strings inside a system. Do NOT invoke for design rationale (

writing-design-docs

) or for reference material nobody executes. If the procedure has not been run at least once, either run it first or label the document a draft; publishing an untested procedure as a runbook is the defect, not the labeling.

适用于所有需要人工执行的内容：Runbook、设置与发布流程、故障排查条目、操作检查表，以及系统中面向运维人员的文本内容。请勿用于设计原理文档（

writing-design-docs

）或无人执行的参考资料。如果流程尚未至少执行过一次，请先执行流程，或将文档标记为草稿；将未测试的流程作为Runbook发布属于缺陷，而非标签标注问题。

Structure

文档结构

Title carries the scope: "MVP runbook (Reddit)", "Release runbook".
Open with what this document is relative to its siblings: "this doc is the sequence; deep detail per step lives in X." State what it does NOT cover.
Legend up front when steps differ in risk, applied to every command: safe to run anytime / operator-only (writes to production) / manual step outside the terminal.
TL;DR happy path first, then the same steps broken out as numbered sections for when the reader needs only one.
Version-pinned prerequisites before any command, each with a check command to confirm it.
Numbered ordinal steps (not bullets), one action each, present tense or imperative, with a visible actor.
Every command copy-pasteable as-is, with concrete placeholder values ("common paths:
```
/public_html/
```
,
```
/www/
```
"). Label variants inside the code block:

bash

undefined

标题需明确覆盖范围："MVP Runbook（Reddit）"、"发布Runbook"。
开篇说明本文档与其他相关文档的关系："本文档为执行流程；各步骤的详细内容请参考文档X。"同时明确说明本文档不涵盖的内容。
风险图例前置：当步骤存在不同风险等级时，需为每个命令标注风险等级：随时可安全执行 / 仅限运维人员操作（写入生产环境） / 终端外的手动步骤。
先提供TL;DR快速执行路径，再将相同步骤拆分为编号章节，方便读者仅查看单个步骤。
在任何命令前标注版本固定的前置条件，每个条件需附带验证命令。
使用编号有序步骤（而非项目符号），每步仅包含一个操作，使用现在时或祈使语气，并明确执行角色。
所有命令需可直接复制粘贴使用，附带具体占位符示例（"常见路径：
```
/public_html/
```
、
```
/www/
```
"）。在代码块内标注不同变体：

bash

undefined

safe mode

安全模式

app sync run --channel=reddit --limit=100

live mode (writes to the provider)

生产模式（写入服务商系统）

app sync run --live --approval-token=...


- Ordered steps state the consequence of wrong ordering inline: "deploy jar, then DB cleanup; wrong order = silent data loss."
- Every state-changing procedure names its rollback, or states plainly that none exists and what that means. A missing undo path is a finding, not an omission the reader discovers mid-incident.
- End with a "verify it worked" section: the observable end state and the command that proves it.
- Mark the preferred path "(recommended)" when several paths exist; document UI and CLI for the same task side by side rather than twice.
- If the runbook will shrink when tooling lands, say so: "when X lands, steps 2 to 4 become one command and this document keeps only the judgment."

app sync run --live --approval-token=...


- 有序步骤中需内联说明顺序错误的后果："先部署Jar包，再执行数据库清理；顺序错误会导致静默数据丢失。"
- 所有涉及状态变更的流程需明确回滚操作，或清晰说明无回滚操作及其影响。缺失回滚路径属于问题，而非让读者在事件中自行发现的遗漏项。
- 结尾添加“验证执行成功”章节：说明可观测的最终状态，以及用于验证的命令。
- 当存在多种执行路径时，标记首选路径为“（推荐）”；同一任务的UI与CLI操作需并列文档，而非重复撰写。
- 如果后续工具上线后Runbook会简化，请明确说明："当工具X上线后，步骤2至4将合并为一个命令，本文档仅保留决策判断内容。"

Troubleshooting entries

故障排查条目

Symptom-first, because the reader arrives with an error message and no vocabulary:

markdown

undefined

采用症状优先的结构，因为读者通常是带着错误信息而来，缺乏专业术语认知：

markdown

undefined

<symptom as the user sees it>

<用户看到的症状>

Symptom: verbatim error strings (searchable) Cause: ... Fix: exact commands


Order diagnostic steps cheapest first. Group entries by failure class. Cross-link the deeper doc instead of inlining it.

症状：原文错误字符串（便于搜索）原因：... 修复方案：具体命令


按排查成本从低到高排列诊断步骤。按故障类型分组条目。关联深层文档链接，而非内联内容。

Migration and deprecation guides

迁移与弃用指南

A migration guide is a runbook whose subject is the change itself. Everything above applies, plus five rules of its own. The surrounding documents are handled by their own skills: the argument for the migration is a design doc, the decision to deprecate is an ADR, the announcement is a changelog entry; this section is the guide the reader executes.

History is the content here, stated positively. The before/after comparison is the job, not a violation: this is the document class the no-history hard rule explicitly carves out. Write "the tag now replaces the manual version bump" freely; that sentence is banned everywhere else and load-bearing here.
The mapping table is the core artifact. Readers arrive knowing the old world; give them old → new per behavior, config key, command, or API, one row each. Prose explains the rows that need it; the table carries the migration.
Rollback is mandatory, per step. Every step names its undo, or states plainly that it is irreversible and what that means for the ordering around it. A migration guide without rollback paths is a proposal to strand people mid-migration.
The deprecation contract carries dates. What stops working, on which date, what happens to stragglers, and where the escape hatch is until then. "Will be removed in a future release" is a banned vague owner wearing a calendar.
Born with an expiry. A migration guide is temporary by design: when the migration completes, it reclassifies as historical and gets the superseded banner pointing at the current-state documentation, never silent deletion. State the completion condition in the guide itself.

迁移指南是主题为变更本身的Runbook，上述所有规则均适用，同时需遵循以下五条专属规则。相关配套文档由对应技能处理：迁移论证属于设计文档，弃用决策属于ADR（架构决策记录），公告属于变更日志条目；本节为供读者执行的操作指南。

以正向表述记录历史对比：前后状态对比是核心内容，而非违规内容：此类文档是唯一不受“禁止提及历史”硬性规则限制的文档类型。可自由撰写“标签现在替代手动版本升级”；这句话在其他所有文档中均被禁止，但在此处是核心内容。
映射表是核心工件：读者熟悉旧系统，需为每个行为、配置项、命令或API提供“旧→新”的映射，每行对应一项。仅对需要解释的行补充说明；映射表承载迁移核心内容。
每步都必须包含回滚操作：每个步骤需明确回滚方式，或清晰说明该步骤不可逆及其对后续流程顺序的影响。无回滚路径的迁移指南等同于让用户在迁移过程中陷入困境。
弃用协议需明确日期：明确说明哪些功能将在何时停止服务，遗留系统的处理方式，以及截止日期前的应急方案。“将在未来版本中移除”属于模糊表述，禁止使用。
自带失效机制：迁移指南本质上是临时文档：当迁移完成后，需将其归类为历史文档，并添加“已被取代”标识指向当前状态文档，禁止静默删除。需在指南中明确迁移完成的判定条件。

Operator-facing strings

面向运维人员的文本

Error messages and log lines are runbook prose with the shortest reading window: keep remediation specific and actionable, and make error states visible rather than letting workflows appear healthy.

错误信息与日志行是阅读窗口最短的Runbook文本：需确保修复方案具体可执行，且错误状态清晰可见，避免流程看似正常但实际存在问题。