在编写运维手册、发布流程、迁移指南等需在压力下执行的文档时…

当有人要在时间压力下按文档执行操作（运维手册、安装/发布流程、故障排查、迁移/弃用指南）时，用真实运行经验写出有序、可复制、标注风险与回滚的步骤。

适用场景

解决思路

1. 先具备 technical-writing 技能（硬性规则、真实性规则、风格）作为前置背景。
2. 从一次真实运行出发编写：每一步都是实际执行过的，每个失败都是真实发生过的；仅在桌面上想象出的流程只是草稿，不是运维手册。
3. 若流程只部分演练过，可按分支如实发布：点名尚未运行过的变体，把该分支标为草稿，并请第一位真实执行者反馈。
4. 若所有分支都没有真实运行支撑，则整篇直接标为草稿。
5. 当命令所需的值确实未知时，保留可见的方括号占位符，绝不臆造，并在发布前通过真实运行填入；真实性优先于可复制粘贴。
6. 标题写明范围，如 “MVP runbook (Reddit)”、“Release runbook”。
7. 开头说明本文档相对同类文档的定位（“本文是操作序列；每步的深入细节见 X”），并声明本文不覆盖什么。
8. 当各步骤风险不同时，在开头放置图例，并应用到每条命令：随时可安全运行 / 仅限运维人员（写入生产）/ 终端外的手动步骤；一步兼具多种属性时标签可组合。
9. 先给出 TL;DR 顺利路径，再把同样的步骤作为编号章节展开，供只需其中一步的读者使用。
10. 在任何命令之前列出锁定版本的前置条件，每条都附带检查命令。
11. 使用编号的有序步骤（不用项目符号），每步一个动作，用现在时或祈使句，并标明执行者。
12. 每条命令都可原样复制粘贴，并给出具体示例值（“常见路径：/public_html/、/www/”）；在代码块内标注变体，例如：# safe mode\napp sync run --channel=reddit --limit=100\n\n# live mode (writes to the provider)\napp sync run --live --approval-token=...
13. 有序步骤要就地说明顺序错误的后果：“先部署 jar，再做数据库清理；顺序反了 = 静默数据丢失。”
14. 每个会改变状态的流程都要写明其回滚方式，或明确说明不存在回滚及其含义。
15. 结尾加一个“验证是否成功”章节：可观察的最终状态以及证明它的命令。
16. 存在多条路径时把首选路径标为 “(recommended)”；同一任务并排记录 UI 与 CLI，而不是写两遍。
17. 如果工具落地后本文会缩短，就说明：“当 X 落地后，步骤 2 到 4 合并为一条命令，本文只保留判断部分。”
18. 故障排查条目采用症状优先格式：## <用户看到的症状>；**Symptom**：逐字错误字符串（可搜索）；**Cause**：...；**Fix**：确切命令。
19. 诊断步骤按成本从低到高排序。
20. 故障条目按故障类别分组。
21. 交叉链接更深入的文档，而不是把内容内联进来。
22. 迁移指南是主题为变更本身的运维手册：上述所有内容都适用，另加五条规则。迁移的论证属于设计文档（writing-design-docs），弃用决定属于 ADR（recording-decisions），公告属于变更日志条目（writing-changelogs）；本节只覆盖读者要执行的指南。
23. 规则一：此处历史就是内容，且以正面方式陈述。前后对比正是本职，不是违规：这是 no-history 硬性规则明确豁免的文档类别。可以自由写“该 tag 现在取代了手动版本号递增”；这句话在其他任何地方都被禁止，在这里却是承重句。
24. 规则二：映射表是核心产物。按行为、配置键、命令或 API 逐项列出旧到新，每项一行。文字解释需要解释的行；表格承载迁移本身。
25. 规则三：回滚是强制性的，且逐步给出。每一步都写明其撤销方式，或明确说明不可逆及其对周边顺序安排的含义。
26. 规则四：弃用契约必须带日期。什么在哪个日期停止工作、滞留者会怎样、在此之前逃生出口在哪里。“将在未来版本中移除”没有指明日期，在此处被禁止。
27. 规则五：诞生即带过期。迁移完成后，负责人把该指南重新归类为历史文档，并加上指向当前状态文档的 superseded 横幅，绝不静默删除。在指南自身中写明完成条件。
28. 面向运维人员的字符串（错误消息和日志行）是阅读窗口最短的运维手册文字：保持补救措施具体可操作，并让错误状态可见，而不是让工作流看起来一切正常。

适用边界 · 注意事项

• 不要用于设计理由类文档（应使用 writing-design-docs）。
• 不要用于没人会执行的参考资料。
• 如果流程一次都没运行过，要么先运行，要么把文档标为草稿；把未测试的流程当作运维手册发布才是缺陷，而不是标签问题。