发布说明与迁移指南起草 —— 发了 changelog 不等于更新了文档,这是两件事

Stripe 给 12 个月迁移期 · 而「发了条 changelog 就当文档更新完了」是全行业的默认操作

一这件事现在是什么样

研发与开发者文档 · 真实业务触发

v2.1 正式版发布在即:API 文档与代码同步巡检 巡检出的 9 处客户在用漂移需要随版说明;其中 `/settlement/reconcile` 的返回结构变更属 Breaking——集成方需要迁移指南;技术负责人要求发布包三件套齐备:面向客户的产品更新说明、面向开发者的迁移指南、面向内部客服的支持简报——三份材料三个受众,一个版本一次交付。

二痛点 · 每条都有来源

不是流程描述,是调研出来的真痛点 —— 每条可点开核对出处

1
「发布 changelog 条目和更新参考文档是两件不同的事——团队普遍做了第一件就当完成了」依据 · Changelog 最佳实践:「发布 changelog 条目和更新参考文档是两件不同的事——团队普遍做了第一件就当完成了」
2
Breaking change 标准管理:迁移期最低 6-12 个月(Stripe 用 12 个月)、Sunset/Deprecation 响应头做机器可读通告——而多数团队的迁移期是「发完就算」依据 · Breaking change 标准管理动作:迁移期最低 6-12 个月(Stripe 用 12 个月,Twilio 提前一整年通知);用 RFC 8594 的 Sunset/Deprecation 响应头做机器可读通告;下线前监控旧端点流量
3
「没有 changelog 的 API 在向开发者广播:我们随时可能弄坏你、我们不追踪自己的变更」——发布说明的欠账直接变成集成方的信任折损依据 · Changelog 的信任功能:「没有 changelog 的 API 在向开发者广播:我们随时可能弄坏你、我们不追踪自己的变更」;规范模板含 Deprecated/Added/Changed/Fixed/Security 分节
4
金融 API 里错误示例会转错钱且不可撤销——迁移指南里的示例代码质量是运营事故级风险依据 · 错误代码示例的后果分级:社交 API 里错误示例发错图只是尴尬,金融 API 里错误示例会转错钱且不可撤销——示例质量是运营事故级风险
5
一半开发者每周损失约 10 小时寻找基本信息——过时文档的代价由使用方和被咨询方双向支付依据 · Atlassian 2025 State of DevEx:一半开发者每周损失约 10 小时只为寻找干活所需的基本信息

三换个做法之后

变化不在「快」,在「参与的角色」和「覆盖的范围」

✕ 现在的做法

  • 「发布 changelog 条目和更新参考文档是两件不同的事——团队普遍做了第一件就当完成了」
  • Breaking change 标准管理:迁移期最低 6-12 个月(Stripe 用 12 个月)、Sunset/Deprecation 响应头做机器可读通告——而多数团队的迁移期是「发完就算」
  • 「没有 changelog 的 API 在向开发者广播:我们随时可能弄坏你、我们不追踪自己的变更」——发布说明的欠账直接变成集成方的信任折损
  • 金融 API 里错误示例会转错钱且不可撤销——迁移指南里的示例代码质量是运营事故级风险

✓ 交给 Agent 之后

  • 多来源文件一次读入,先做口径与完整性校验,再开始算
  • 每条结论绑定来源文件、字段或条号,可以被审
  • 产出是企业真会流转的正式件(带签批栏),不是一张展示用的表
  • 该拦的地方给出「现在还不能提交」,并给不用干等的替代方案

四场景闭环

5 步 · 每一步的产出都是下一步的输入

第 1 步
变更分类登记本版全部变更按 Added/Changed/Deprecated/Fixed/Security 五分节归类
第 2 步
Breaking 判定与影响挂接逐条判定是否 Breaking;是则挂受影响集成方与端点级 diff
第 3 步
迁移指南起草端点级变更说明 + 迁移示例(逐条验证)+ 弃用时间表建议
第 4 步
三受众分别成稿客户版/开发者版/客服支持简报——同一事实三种讲法
第 5 步
发布包汇编与签发流转三件套 + 通知范围建议,签发栏留空

要准备什么

API 文档与代码同步巡检 巡检报告(本期漂移台账)
9 处客户在用漂移——发布说明的事实骨架
本版合并记录与发版清单
Added/Changed/Deprecated/Fixed 的原始事实
受影响集成方清单(联调工单+集成登记表)
谁需要收到哪份材料——通知范围依据
上一版发布说明(历史欠账对照)
哪些「上次说要做」的这次真做了——口径连续性检查

为什么这个场景值得做

痛感 5 × AI 适配 3 ÷ 落地难度 2 = 7.5

最大差异点 · 发布包三件套面向三个受众分别成稿,不是一份文档改三遍格式:客户版讲「对你的影响」(无技术术语);开发者版讲「怎么迁」(端点级 diff + 验证过的迁移示例 + 弃用时间表);客服版讲「客户会来问什么」(预判问题清单 + 应答口径)。原料直接来自 API 文档与代码同步巡检 的漂移台账与合并记录,不重新考古。

评分口径:痛感看「这事没做好谁会生气、生气到什么程度」; AI 适配看「输入是否非结构化、是否要跨部门取数、错了能不能当场看出来」; 落地难度是分母 —— 需要客户先做数据治理的场景,分数会被压得很低。

五会产出什么

判断标准只有一个:这份东西能不能直接进企业的流程

正式件本体
发布包三件套.docx
正式件 · 客户版/开发者版/客服版 · 含弃用时间表建议与签发栏
可派发清单
迁移示例验证记录.xlsx
11 个示例 · 验证状态/验证日期/失败原因 · 未验证不进指南
可派发清单
受影响集成方通知范围表.xlsx
集成方 × 应收材料版本 × 建议发送时点 · 客户成功确认

这套东西不承诺什么

迁移指南的代码示例必须逐条经过可运行验证,未验证示例标注「草稿」;弃用时间表只起草建议(对照行业惯例给区间),正式承诺由产品与技术负责人签发;客户通知的发送范围与时间由客户成功确认,本场景只出材料不出发送动作。

想看具体怎么跑?

Live Demo 里有一个完整案例的每一步,包括 Agent 在哪一步拦住了