# 好的交接文档，让客户不必再回头找你

> PostHog 的标准是陌生人拿来就能读懂上手；多数文档失败，因为写在最忙的一周，又没有出处。

原文: https://fdetimes.net/zh/guides/write-handover-docs-clients-can-run/

设想这样一个场景：周五是你在项目上的最后一天。把订单从客户 ERP 同步到数据仓库的数据管道已经平稳运行了两周，演示做完了，客户也很满意。三周后，客户发来消息：昨晚的任务失败了，能帮忙看看吗？

这条消息说明交接失败了，尽管代码本身没有任何问题。PostHog 的 FDE 手册对交付物何时算“完成”定了一个非常清楚的标准：客户团队里一位陌生人拿到它，无人讲解也能读懂，理解范围，照着建议执行，并且永远不需要再联系 FDE 团队。

PostHog 把文档和培训阶段定义为所有权的移交，目的是团队离开后，客户能自己运行这套系统。

对前线部署工程师（FDE）来说，这项能力区分了“把项目做完”的人和“留下一套能持续运转的系统”的人。面试时也值得把它讲具体，用结果说话，而不是用形容词。

## 为什么交接文档常常没用？

Tandem 是一家撰写 FDE 工作流程相关内容的公司，它指出了一个很平常的原因：即将离开的人恰恰在最忙的几周写文档，同时还要收尾开发。可想而知，写出来的文档记录的是作者容易想起的内容，而不是接手者需要的内容。

Tandem 还指出，这类文档是一份无法核实的快照。像“客户同意忽略已取消订单”这样的一句话，如果没有链接到邮件或会议纪要，读者只能再去问客户一遍。用 Tandem 的话说，没有出处的记录只是一种说法。

第三个问题是时间。Google 的 SRE 书提醒，在快速变化的环境中，运维文档很快就会过时。新人最需要最新的文档，却往往觉得自己没有足够的权限或理解去修改它。

## 一套交接文档，五类内容

解决办法是不再把交接当成“一份长长的 README”，而是按读者要做的事情来拆分。

Canonical 的 Daniele Procida 提出的 Diátaxis 框架提供了一种实用的划分方式。操作指南是完成某项具体任务的分步做法；参考用来查询系统的事实；解释说明系统为什么这样设计。

对交接文档来说，在这三类之外再加两层会更有用。最上面是一页简短的封面页，按照 Tandem 的建议，只回答四个问题：承诺了什么、决定了什么、还有哪些风险、下一步做什么。

最下面是诊断部分，因为 Google 的 SRE 书提醒，不要只用流程、检查清单和预案来培训人：运维人员需要懂得如何推理分析书中没有覆盖的故障。

| 类型 | 读者需要什么 | 订单管道中的例子 |
|---|---|---|
| 封面页 | 五分钟内掌握全貌 | 范围、决策、风险、下一步及具体负责人 |
| 操作指南 | 立刻完成某项具体任务 | 为漏跑的某一天重跑任务 |
| 参考 | 查询某个事实 | 运行时间表、目标表、凭据存放位置 |
| 解释 | 理解系统为什么是现在这样 | 为什么用增量同步而不是全量同步 |
| 诊断 | 独立找出陌生事故的原因 | ERP 与数据仓库的行数不一致 |

## 示例：订单管道的封面页

回到上面假设的数据管道。它的封面页可以是这样，每一行都链接到出处：

```markdown
# 交接：ERP → 数据仓库订单同步管道

## 承诺
- 每晚同步新增和修改的订单。[链接：启动会纪要]
- 不包括库存数据（推迟到后续阶段）。[链接：确认邮件]

## 决定
- 基于 updated_at 列做增量同步。原因：见 explanation/incremental.md
- 保留已取消订单，并用 is_cancelled 标记。[链接：与财务团队的会议纪要]

## 风险
- ERP 升级时可能变更 schema；任务会在 validate 步骤失败。

## 下一步（按顺序）
1. Lan（数据团队）把任务失败告警转到她团队的值班频道。
2. Minh（IT）在 ERP 凭据过期前完成轮换。
3. Lan 在 staging 环境试运行 how-to/backfill.md。
```

薄弱的文档通常在“下一步”这一节写上“需要持续观察”。PostHog 要求下一步必须具体、有先后顺序，并指派给具体的人。没有负责人的任务，就是没人会做的任务。

“决定”一节指向解释文档，而不是重复内容。PostHog 的建议是，交接应记录做了什么以及为什么这样做。理由很重要：一年后，客户方会有人想把同步改成全量来“简化”系统，只有解释文档能告诉他们当初为什么否决了这个方案。

封面页也不照抄运行时间表或配置。Tandem 提醒，如果文档超过几页，说明它在重复本该由系统保存的内容。时间表放在调度器的配置文件里，参考文档只需指向那里。

## 诊断：教会怎么思考，而不只是点哪里

“重跑任务”的操作指南帮客户应对你预料到的故障，诊断部分则用于你没有预料到的故障。

对这条管道来说，一份好的诊断页从症状出发（“数据仓库里的订单比 ERP 少”），再按检查难易程度列出假设：任务有没有运行，是否有订单的 updated_at 落在时间窗口之外，是否存在时区不一致。

每个假设都附上验证方法，比如在两边按天统计订单数的查询。读者由此学会如何逐一排除原因，下次遇到别的症状也能用同样的方法。

## 动手做：五个步骤

**第 1 步：从第一周开始写，而不是最后一周。** 这样就能避开 Tandem 所说的陷阱。每做出一个决定，就在当时往“决定”一节加一行，并附上出处链接。

**第 2 步：写操作指南和参考。** 临近交接时，为客户最常做的三到五项任务写操作指南，再写参考文档，指向配置实际所在的位置。

**第 3 步：写解释和诊断页。** 解释针对后来者容易想推翻的决定；诊断页针对最常见的症状。

**第 4 步：做 PostHog 的测试。** 把文档交给客户方一位没有参与过项目的人，请他照着某份操作指南执行，你全程不说话。他提出的每个问题，都是需要补上的缺口。

**第 5 步：指定文档维护人。** 明确客户方由谁负责更新文档，并把文档放在此人方便编辑的地方，避免出现 SRE 书提醒的情况：新的运维人员不敢动手修改。

## 常见错误

最常见的错误是写给自己看：使用内部缩写，跳过“显而易见”的步骤，而这些步骤只对搭建系统的人显而易见。第二个错误是把所有内容塞进一个文件，结果半夜处理事故的人得先翻过三页设计历史。

第三个错误是把文档放在自己公司的 wiki 里，客户无法编辑。Google 的 SRE 书早已提醒，运维文档老化得很快；如果客户方的人改不了它，它就会和真实系统越离越远，却没人修正。

## 这项能力在简历上怎么体现

阅读 FDE 岗位描述时，留意岗位是否提到把系统移交给客户团队。在简历上，不要写“编写了文档”，而要描述结果：你离开后，哪个客户团队独立运行了系统，他们不用联系你就能做哪些事。

本周的练习反过来做：找一份你曾经接手过的交接文档或 README，列出你当时不得不问别人的每一个问题，再把每个问题归入上面五层中的一层。哪一层积累的问题最多，就是轮到你交接时最容易忽视的那一层。

**本周动手试试:**

- 选一个你负责的系统，写一份包含四部分（承诺、决定、风险、下一步）的封面页，每项任务都写明具体负责人。
- 把一份操作指南交给从未接触过该系统的同事，默默看他操作，记下他每一次需要问你的地方。
- 为最常见的故障写一页诊断：症状、如何看日志，以及按排除顺序排列的假设。

## 信源

- [Working with customers - Handbook (PostHog)](https://posthog.com/handbook/forward-deployed-engineering/working-with-customers)

- [FDE handoffs: keeping an engagement alive when the builder changes](https://usetandem.ai/blog/fde-handoff-runbook)

- [Diátaxis, a new foundation for Canonical documentation](https://canonical.com/blog/diataxis-a-new-foundation-for-canonical-documentation)

- [Accelerating SREs to On-Call and Beyond (Site Reliability Engineering, Google)](https://sre.google/sre-book/accelerating-sre-on-call/)
