S25-A05 · 技术写作：把方案、复盘与文档写出作用

写了不少文档，评审时没人点开，出事时没人回看，半年后自己都不敢照着执行。原因通常不是文笔，而是文档没有明确"要读者做什么"——它记录了过程，却没有改变任何人的行为。判断一份文档有没有用，只看一件事：读者读完之后的动作，是否与不读时不同。

1. 目标：改变读者行为

文档	读者	读完后应该发生的动作
方案	决策者、相关团队	批准、否决，或提出具体异议
复盘	当事团队、管理者	改流程、改监控、改优先级
操作手册	执行者（可能是三个月后的自己）	按步骤做完，并在验证点确认
背景说明	后来者	不再重复问同样的问题

写之前先写一句"读完请做 X"。写不出这句，说明文档还停在自我表达阶段。

2. 三类文档的骨架

方案：问题 → 目标与非目标 → 选项 → 取舍 → 建议 → 验证方式 → 风险
复盘：时间线 → 影响 → 根因 → 处置过程 → 改进项（含负责人与期限）
手册：前置条件 → 步骤 → 验证点 → 回滚 → 常见失败

类型	必答项	最常见的缺失
方案	为什么不是别的方案	只写"我们打算这么做"
复盘	根因与改进项的对应关系	改进项与根因无关
手册	怎么确认做对了	只有步骤，没有验证

3. 方案文档：没有选项就没有方案

段落	必须回答	不合格的写法
问题	现状造成了什么可观测损失	"为了提升系统能力"
目标/非目标	这次不解决什么	目标列了八条，没有非目标
选项	至少两个可行方案	只有一个方案，其余是 straw man
取舍	每个选项的代价与失效边界	只列优点
建议	选哪个，为什么现在选	"请领导决定"
验证	上线后用什么指标判断成功	"观察一段时间"

**选项 B：异步补偿（推荐）**
- 收益：峰值削平，失败可重试
- 代价：状态可见延迟到秒级；需要新增补偿任务与对账
- 失效边界：补偿任务积压时，用户看到长时间"处理中"
- 不选它的条件：若业务要求强一致，退回选项 A

"没有选项就没有方案"的实质是：决策者需要的是取舍结构，不是单一结论。只有一个选项时，评审退化成背书，风险也就没人看。

4. 复盘：避免写成检讨

段落	内容要求	常见偏差
时间线	事实时间戳，不含评价	把推测写成时间点
影响	用户/收入/数据的量化口径	只写"影响部分用户"
根因	机制链条，能推出"下次怎么防"	停在"人为失误"
处置	何时发现、何时止血、谁决策	只写最终方案
改进项	每条对应一个根因，带负责人与期限	改进项与根因无关

**根因**
配置项 `pool.max` 未随实例规格调整（机制）
→ 高峰期连接耗尽（触发）
→ 重试无退避放大流量（放大）
改进项 1 对应第一环：配置纳入启动自检
改进项 2 对应第三环：重试加指数退避与上限

判据：根因写到"能直接推出改进项"的粒度为止。"某人操作失误"不是根因，是现象；往下一层问"为什么这个操作没有拦截"，才是根因。

5. 操作手册：验证点比步骤重要

部分	作用	缺了会怎样
前置条件	版本、权限、依赖、备份	执行到一半才发现缺权限
步骤	可直接复制的命令	读者要自行翻译
验证点	每步之后如何确认成功	错了也继续往下走
回滚	回到上一步的具体命令	出事时现场 improvisation
常见失败	报错与对策	同一问题被重复排查

# 步骤 3：切流量到新版本
# 验证：两个版本都在返回 200，且新版本占比符合预期
curl -s -o /dev/null -w '%{http_code}\n' https://example.com/health
# 回滚：把权重改回 100/0，再确认旧版本健康检查通过

手册的读者是未来的自己：写的时候假设自己已经忘了上下文，只剩这份文档。

6. 读者定位决定详略

读者	关心	可以省略
决策者	结论、代价、风险	实现细节、命令
执行者	步骤、前置条件、验证	背景论证
后来者	为什么这样设计	当时的临时手段

同一份材料服务三类读者时，正确做法是分层：结论与取舍在前，实现附录在后，而不是折中成一份谁都不满意的中等详略。

7. 写作顺序

1. 先写结论与建议（三到五句）
2. 再写支撑结论的三条理由
3. 再写取舍与被否决的选项
4. 最后补数据、附录、命令
5. 回读第一段：它是否已经能让人做决定

先写论证再写结论，几乎必然写成"过程记录"：读者要读到最后才知道你想干什么。倒金字塔结构不是文风偏好，而是降低读者的决策成本。

8. 图表的边界

场景	用图	用文字
调用链、时序、状态迁移	✅ 一张图省三段	文字要读者自己拼
两三个数值对比	表格足够	图反而增加阅读成本
取舍权衡	表格（选项×维度）	折线图会误导
精确流程步骤	编号列表	流程图看不出"必做"

判据：这张图能否替代三段以上的文字。不能，就别画——维护一张过期的图，比没有图更危险。

9. 术语一致性

反例	问题	改法
同一概念交替用"任务/作业/Job"	读者以为是三个东西	首次出现给定义，之后固定一个词
"服务"既指进程又指团队	责任主体混淆	进程叫 service，团队叫 team
中英混用同一名词	检索失效	术语表规定主用词，括号给别名

术语表不需要长，五到十个词就够，但它必须在项目内被引用，否则只是装饰。

10. 存放与检索

决策	选项	判据
放哪	代码库 / wiki / 文档平台	是否与代码同生命周期
谁维护	作者 / 属主团队	有没有明确的最后责任人
过期怎么标	顶部状态行 / 目录归档	读者能否三秒判断可信度
怎么找	命名规范 / 索引页 / 全文搜索	新人能否独立找到

> 状态：有效（最后核对 2026-11，适用 v2.x）
> 属主：平台组　过期条件：v3 发布后失效

与代码强耦合的文档（接口、部署步骤）放代码库，随 PR 一起改；决策类文档放可检索的地方，但要留状态行。

11. 时间投入与收益

写一份方案：2 小时
没有它：评审会 1 小时 + 后续 5 次单独解释 × 15 分钟 ≈ 2.2 小时
第二次复用（新人、交接、半年后自查）：再省一次同等时间
结论：文档的收益在第 2 次被读时才为正，只读一次的场景不必写

这不是鼓励多写，而是给出写与不写的分界线：会被反复读、会被多人读、会在没有作者在场时被读——三条中占一条，才值得结构化。

12. 评审与修改循环

轮次	目标	常见错误
自评	结论能否独立成立	直接发给 reviewer
结构评审	段落顺序、必答项是否齐	一上来抠字
事实评审	数字、版本、引用可核对	用"大概""差不多"
定稿	状态行、属主、过期条件	忘了标状态

评审提问模板：
1. 这份文档要我做什么决定？
2. 有没有被我忽略的选项？
3. 哪一条结论缺少证据？

评审意见要么改，要么明确拒绝并写理由；悬空的意见会让下一轮评审失效。

13. 排错

现象	原因	处理
评审没人提意见	没有明确要决策的问题	开头写"请确认 A 或 B"
文档被读但没被执行	缺验证点与回滚	补可复制的命令
半年后无法照做	缺版本与前置条件	顶部加状态行
复盘像检讨	根因停在人为失误	往机制层追问一层
同一问题反复解释	结论埋在文中	结论前置，单独可引用
图与实现不符	图无属主	图与代码同库，随 PR 更新

14. 边界

场景	建议	理由
口头两分钟能说清	不写	结构化成本高于沟通成本
纯个人笔记	不要求结构	结构服务他人，不服务自己
一次性排查记录	记要点即可	复用概率低
代码能自解释的逻辑	不写重复说明	文档会与代码分叉
需要精确到行的说明	写进代码注释	注释与代码同处才不易过期

一句话收尾：技术文档的价值不在"记录了什么"，而在"读者因此做了什么不同的事"。写不出这个"不同"，就先别写。

15. 自测

如何用一句话判断一份文档是否值得写？
为什么"只有一个选项的方案"不算方案？
复盘的根因写到什么粒度才算够？
操作手册里哪一部分最常被省略，后果最严重？
什么情况下该用图，什么情况下表格更合适？
文档顶部的状态行解决了什么问题？