Stripe 给 12 个月迁移期 · 而「发了条 changelog 就当文档更新完了」是全行业的默认操作
研发与开发者文档 · 真实业务触发
v2.1 正式版发布在即:API 文档与代码同步巡检 巡检出的 9 处客户在用漂移需要随版说明;其中 `/settlement/reconcile` 的返回结构变更属 Breaking——集成方需要迁移指南;技术负责人要求发布包三件套齐备:面向客户的产品更新说明、面向开发者的迁移指南、面向内部客服的支持简报——三份材料三个受众,一个版本一次交付。
不是流程描述,是调研出来的真痛点 —— 每条可点开核对出处
变化不在「快」,在「参与的角色」和「覆盖的范围」
5 步 · 每一步的产出都是下一步的输入
痛感 5 × AI 适配 3 ÷ 落地难度 2 = 7.5
最大差异点 · 发布包三件套面向三个受众分别成稿,不是一份文档改三遍格式:客户版讲「对你的影响」(无技术术语);开发者版讲「怎么迁」(端点级 diff + 验证过的迁移示例 + 弃用时间表);客服版讲「客户会来问什么」(预判问题清单 + 应答口径)。原料直接来自 API 文档与代码同步巡检 的漂移台账与合并记录,不重新考古。
评分口径:痛感看「这事没做好谁会生气、生气到什么程度」; AI 适配看「输入是否非结构化、是否要跨部门取数、错了能不能当场看出来」; 落地难度是分母 —— 需要客户先做数据治理的场景,分数会被压得很低。
判断标准只有一个:这份东西能不能直接进企业的流程
迁移指南的代码示例必须逐条经过可运行验证,未验证示例标注「草稿」;弃用时间表只起草建议(对照行业惯例给区间),正式承诺由产品与技术负责人签发;客户通知的发送范围与时间由客户成功确认,本场景只出材料不出发送动作。
Live Demo 里有一个完整案例的每一步,包括 Agent 在哪一步拦住了