FDE Times 数据在招 FDE 职位 873▼9 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 55在招公司 181支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 98
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

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

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

分享微博

要点速览

  • PostHog 对“完成”的标准:客户团队里一位陌生人拿到文档,无人讲解也能理解范围、照着执行,并且永远不需要再联系 FDE 团队。
  • 交接文档之所以失败,是因为要离开的人在最忙的那一周写它,记下的是自己容易想起的内容,而不是接手者需要的内容。
  • 封面页控制在几页以内;把操作指南、参考和决策背后的理由分开;每条结论附上出处,并指定负责更新文档的人。
交接文档的五个层次自上而下堆叠。最上层为橙色的封面页:承诺、决定、风险、下一步。中间三层分别是操作指南(完成具体任务)、参考(查询事实)和解释(为什么是现在这样)。最下层是诊断,用于应对意料之外的故障。
中间三层来自 Daniele Procida 的 Diátaxis 模型。封面页的四个问题参照 Tandem 的建议,诊断部分源自 Google SRE 书中的一项提醒。

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

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

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

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

为什么交接文档常常没用?

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

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

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

一套交接文档,五类内容

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

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

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

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

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

示例:订单管道的封面页

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

# 交接: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,列出你当时不得不问别人的每一个问题,再把每个问题归入上面五层中的一层。哪一层积累的问题最多,就是轮到你交接时最容易忽视的那一层。

这篇文章对你有帮助吗?

4 个信源
路线图上的下一篇 · 阶段 5: 部署上线AI 项目里,演示是最容易的一步Gartner 预计至少 30% 的生成式 AI 项目止步于概念验证,补上这道缺口正是 FDE 的工作。