# 客户得找你才能运行系统，就是缺文档

> 《Docs for Developers》以翻译狗叫的 API 为例，虽非为 FDE 而写，却适用于交接，建议买第二版。

原文: https://fdetimes.net/zh/books-courses/docs-for-developers-fde-reading-guide/

一本严肃的技术文档书，贯穿全书的示例却是 Corg.ly：一个把狗叫翻译成人话的 API。玩笑背后是每个前线部署工程师（FDE）都要回答的问题：你走之后，客户团队能自己运行这套系统吗？

Kelsey Hightower 在序言中写道：如果说开发者是软件行业的超级英雄，那么缺少文档就是他们的氪石。把这块氪石放到客户现场，大概就是这样一条 Slack 消息：“token 又过期了，怎么轮换来着？”

你可以按时交付，演示也可以很漂亮。但如果每项运维操作都得打电话找你，你其实什么都没交接出去，也很难抽身去下一个客户。所以这本书值得 FDE 花时间读，尽管它并不是为 FDE 写的。

**要点:** 如果客户得打电话给你才能运行系统，那么缺的那份文档就是你。

## 为工程师而写，但不是为客户项目而写

Jared Bhatti、Zachary Sarah Corleissen 与几位合著者写这本书，用他们在[官方网站](https://docsfordevelopers.com)上的话说，是要把几十年的技术写作经验推广给最需要的人。

Write the Docs 播客评价说，这本书专门为开发者而写，内容从分析读者一直讲到起草、编辑和发布。

书籍网站上的发布文章日期是 2021 年 10 月 7 日。第二次印刷加入了作者所说的“在写作过程中使用 AI 的思考与建议”，如果要买，就选这一版。

这本书的局限在于背景设定：它跟随一个软件团队发布新产品。新产品的读者大多是陌生人，而你的读者有名有姓、有职位，一个电话就能找到。这反而是优势，因为你写的每样东西都能马上拿真人来检验。

因此，下面三个思路虽然从书中章节出发，但搬到客户现场的工作要你自己完成。文中的示例和衡量方法是应用建议，不是书里印好的流程。

## 思路一：没有哪份文档是写给“客户团队”的

[目录](https://docsfordevelopers.com/table-of-contents/)开篇是第 1 章：理解你的读者。对 FDE 来说，这也是起点，因为“客户团队”并不是同一个读者。

假设你正在把一个 Agent 接入一家物流公司的仓储系统。凌晨 2 点值班的工程师需要回滚步骤，分析师需要知道每个数据字段的含义，IT 管理员需要知道怎样轮换 token、分配权限。一份 40 页的 README 会让这三个人都失望。

到现场的第一件事，是写下三列：谁在读，他要完成什么，打开文档时处在什么情境。如果填不出来，说明你的需求调研还漏了一些问题。

## 思路二：统计问题数，但别马上相信这个数

第 8 章讲收集反馈并融入文档，第 9 章讲衡量文档质量。对 FDE 来说，最便宜的反馈来源已经躺在与客户共用的 Slack 频道里。

举个假设的例子：2 周内，客户团队问了你 40 个问题，其中 26 个集中在三个主题：token 轮换、重试处理和 schema 变更。

也就是说，65% 的支持工作量恰好来自三页并不存在的文档。写好这三页，如果接下来 2 周问题降到 18 个，总数就少了 22 个，降幅 55%。这个数字可以汇报，但还算不上证据。

客户团队对系统越熟悉，问得就越少，哪怕你再没写过一页文档。所以要按主题拆分：如果三个已写文档的主题从 26 降到 4，其他主题保持在 14，那文档多半起了作用。

如果所有主题一起下降，可能只是团队用熟了。如果某页文档已经存在，大家却还在问，先检查它是否放在了对的位置、是否写给了对的读者，再决定要不要多写。

光看问题数还不够，因为客户可能不好意思问，然后把事情做错。再加一项测试：把 runbook 交给一位从没碰过系统的客户工程师，你在旁边一言不发，记下对方每一个卡住的地方。每当你忍不住开口解释，就说明文档里缺了一行。

## 思路三：文档不仅需要作者，还需要接收人

第 11 章讲文档的维护与弃用。对 FDE 来说，这可能是最难落地的一章：你会离开，文档却留下来，并随着客户每一次配置变更而过时。

交接日之前，确保每份文档都写明客户方负责人的名字和下一次审阅日期。过时的页面要清楚标注，或者干脆删掉，因为半夜里一份错误的 runbook 比没有 runbook 更糟。

附录 A 还提出一个问题：什么时候该聘请专职技术写作人员。随着文档规模增长，这个问题值得带到客户会议上讨论，因为 FDE 不应该一直维护每一页直到最后。

## 按什么顺序读？

这本书最适合自己写文档却从没学过怎么写的工程师，尤其是即将第一次交接的人。如果你是资深技术写作者，一本写给开发者的书带给你的新东西可能不多。不要像读教材那样从头读到尾，而要按项目节奏来读。

| 书中部分 | 现场何时需要 | FDE 该做什么 |
|---|---|---|
| 第 1 章：理解读者 | 第一周，与需求调研同步 | 列一张表：谁在读、要完成什么、处于什么情境 |
| 第 8 章：反馈 | 客户团队开始独立使用系统时 | 把 Slack 和邮件里的问题汇总成一份清单 |
| 第 9 章：衡量质量 | 交接前几周 | 确定问题数基线，并做无协助测试 |
| 第 11 章：维护与弃用 | 离开项目之前 | 指定负责人和审阅日期 |
| 附录 A：聘请专职人员 | 文档规模超出项目团队能力时 | 向客户提出这个问题 |

坐下来写第一页时，再读起草、编辑和发布的部分。如果打算用模型起草，同时读第二次印刷新增的 AI 建议。无论用什么工具，交付之前都要在客户环境里亲自把每条命令重新跑一遍。

## 把文档变成简历上的证据

如果简历上只写“擅长编写文档”，这项能力很难让人信服。换成这样一句：“为三个最常被问到的主题编写 runbook：2 周后相关问题从 26 个降到 4 个，新工程师可以在无协助的情况下照着操作”，分量就重得多，前提是这些数字是你亲自测出来的。

没有真实客户，也可以为某个开源 API 写文档，请朋友照着操作，再把修改前后的两个版本都发布出来。

阅读 FDE 岗位描述时，留意 handoff、enablement 这类词，然后问招聘方：FDE 离开后由谁维护文档？如果对方答不上来，这份活多半会落到你头上。

部署真正的考验不在你驻场的时候，而在你离开后的那一周：客户那边有人遇到问题，打开的是你的文档，而不是 Slack。

**本周动手试试:**

- 导出客户团队过去 2 周的问题，按主题分类，为被问得最多的主题写一份文档。
- 请一位不了解系统的工程师照着你的某份 runbook 操作，你在旁默默观察，记下对方每一个卡住的地方。
- 在每份要交给客户的文档顶部，加上一行负责人和下一次审阅日期。

## 信源

- [Docs for Developers (trang sách chính thức)](https://docsfordevelopers.com)

- [Table of Contents – Docs for Developers](https://docsfordevelopers.com/table-of-contents/)

- [WTD Episode 35: Docs for Developers book, with Jared Bhatti and Zachary Sarah Corleissen](https://podcast.writethedocs.org/2021/10/31/episode-35-docs-for-developers)