用WorkBuddy把一份后端接口文档改写成新人上手指南
问题：接口文档是给“已经会的人”看的
后端接口文档通常写得很严谨：路径、方法、参数表、返回示例、错误码，一应俱全。但新人拿到手，第一反应往往不是“我会调了”，而是“我该从哪个接口开始”。文档按资源组织，新人需要的是按任务组织，这两者之间的落差，就是上手成本。
这次我拿 BackendWiki 的接口与工程实践条目 当素材，用 WorkBuddy 试着做了一次改写，目标是产出一份“第一天照着做就能跑通第一个请求”的指南。
改写的结构设计
没有让 AI 直接“改写文档”，那样大概率会得到一份更短的同样文档。我先把目标结构定死，再让它填：
- 最小闭环：只选一个最简单、无前置依赖的接口，目标是十分钟内拿到一次成功响应。
- 环境准备清单：需要什么工具、哪里拿凭证、本地怎么起服务，逐条写成动作。
- 第一次请求的完整过程：包含可直接复制的命令、预期返回、以及“看到什么算成功”。
- 三个最常见的失败：鉴权、参数格式、环境地址，每个给出报错特征与排查方向。
- 下一步读哪里：明确指向原文档中该深入的章节，而不是让人从头再读一遍。
第 4 部分是重点。新人卡住的地方高度集中，与其等他遇到问题再去搜索，不如提前把报错特征摆出来。
执行中的两条约束
不许新增文档里没有的信息。 我明确要求所有参数名、路径、错误码必须来自原文，无法确认的标为“待确认”。AI 很擅长“合理补全”，但接口文档里一个臆造的字段名就能让新人白折腾半小时。改写完成后，我又让它做了一遍逐项比对，把每个硬信息标上来源位置。
保留原文链接。 每个章节末尾都留了对应文档的入口。指南负责“带进门”，原文负责“查得准”，职责分开后维护也轻松。需要补 REST 概念时，再引导到 前端 Wiki 的工程化分层目录 顺一遍基础，不必塞进指南正文。
结果与复盘
改完的指南不到原文三分之一长，但新人第一次调通的时间从平均大半天降到半小时以内。回头看，起作用的主要不是文笔，而是换了组织维度：从“系统有哪些接口”变成“你要完成的第一件事是什么”。
一个附带收获是，这份指南反过来暴露了原文档的两处缺口——凭证获取方式写在别处、错误码缺少说明。这类问题在按资源组织的文档里很难被发现，一旦按任务串一遍就藏不住了。
什么时候值得做
如果团队经常有新人、且接口数量不少，做一次很划算；如果只有两三个人、接口稳定，直接写个 README 反而更快。工具只是把改写成本降下来了，要不要维护第二份文档这个判断，还是得人来做。
补充一句：这类“把参考资料重组成可操作材料”的活儿，和 万象云档里那些按主题编排的文档 思路相通——先想清楚读者要完成什么，再决定内容怎么排。