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

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

!
演示模式 · 可视化预演

本页展示的是「应该怎么跑、每一步看什么、交付什么」,用的是真实业务格式的脱敏构造数据, 不宣称已接入客户生产系统,也不承诺任何效率提升百分比。 案例设定:明衡软件研发部。v2.2 发版在即:本版变更 39 项(Added 8 + Changed 12 + Deprecated 3 + Fixed 15 + Security 1),其中 Breaking 1 项(/export/legacy v1 关停);迁移示例 11 个验证中,集成方 6 家需通知。

输入文件
4 份
本版变更
39 项 · 五分节
Breaking
1 项 · 弃期建议稿
发版窗口
下周二 · 三受众材料齐
输入

软件公司手上能拿到的东西

不需要整理格式、不需要改文件名 · 直接拖进对话框
01_变更合并记录_v2.2.xlsx
v2.2 版本全部合并记录归集——发布说明五分节的唯一数据源
研发部导出 · 发版前冻结
02_API文档漂移台账_本周.xlsx
API 文档与代码同步巡检 本周巡检产出——迁移示例与修复说明的素材来源(上游材料)
研发部 · 本周巡检
03_迁移示例集_11个.xlsx
多币种与导出相关的 11 个迁移示例——每个都要过验证关
研发部编写 · 发版前验证
04_集成方与材料版本.xlsx
受影响集成方清单——应收材料与版本要求(与 API 文档与代码同步巡检 在用清单同源)
客户成功部维护 · 每月更新

注意标橙色那一份 —— 01_变更合并记录_v2.2.xlsx。它研发部导出 · 发版前冻结,平时压根不在核对范围里。这个场景的价值,很大一部分就来自把它读进来。

提示词

就说这么几句

没有模板、没有表单 · 专业规则由 Skill 兜底
v2.1 正式版要发了。这是 API 文档与代码同步巡检 的巡检报告(9 处客户在用的漂移),这是本版全部合并记录,这是受影响的集成方清单,还有上一版的发布说明。 帮我出发布包三件套: 1. 客户版更新说明——只讲「对你的影响」,别堆技术术语。 2. 开发者版迁移指南——`/settlement/reconcile` 的返回结构变更是 Breaking 级,端点级 diff、迁移示例、弃用时间表都要有。示例逐条跑一遍,跑不通的标出来给我。 3. 客服支持简报——客户最可能来问的十个问题和应答口径。 上一版说了要上但这次还没合并的功能,别写进来。弃用时间表给建议稿,正式承诺那栏留空,我们自己定。

五分节结构、Breaking 判定、三受众改写规则在能力包里;原料是 API 文档与代码同步巡检 台账与合并记录——发布说明从此是漂移台账的下游,不是又一次考古。

触发

v2.2 发版在即 · 39 项变更要拆成三份材料发给三种人

发了 changelog 不等于更新了文档——这是两件事

客户看的是「这次多了什么」、开发者看的是「接口怎么迁」、客服看的是「明天会接到什么电话」——同一版变更,三份材料三个口径,原料都是同一份合并记录。

1

变更五分节归集 · 39 项一项不落

发布说明的分节与行业通行惯例对齐——客户见过这种格式
分节数量客户可见度
Added8客户版高亮
Changed12开发者版逐条
Deprecated3三受众都发 · 含弃期表
Fixed15客户版摘要
Security1客户版高亮 · 单独说明
合计39—
该拦的边界 · changelog 与文档更新分开对待最省事的做法是发一份 changelog 就当文档更新完了——changelog 记录「这一版改了什么」,文档站记录「现在是什么样」,两个问题两种答案。发版清单里文档更新是独立一项(API 文档与代码同步巡检 台账里的 9 处修复随本版进文档站),不靠 changelog 顶替。
2

Breaking 1 项 · /export/legacy v1 关停的弃期建议稿

弃期承诺有依据、可签发、可追踪——但只出建议稿
接口处置弃期建议依据
/export/legacy v1本版关停 · Breaking6 个月过渡期对照行业惯例 6-12 个月 · 使用方仅华驿 1 家
/report/legacy v1保留12 个月使用方珠江医药 · 改造成本高
/fx/manual v0保留3 个月无集成方在用
从历史里想起的「口头弃期」上一版关停 /export/batch 旧端点时,弃期是客户成功在群里口头说的「大概半年后关」——半年后客户炸群,翻遍文档站找不到书面依据。这次的弃期表进发布包、白纸黑字,建议稿给依据和区间,正式承诺由人签发——这条边界是信任的护城河。
3

迁移示例 11 个 · 9 个已过验证,2 个待修正不进指南

金融级接口的示例质量第一次有了硬关卡
示例编号对应接口验证状态处理
EX-01 ~ EX-08/settlement · /fx · /report 各端点通过 · 8 个进指南
EX-09/export/legacy 迁移到 v2待修正修正并复验后补入
EX-10/export/legacy 迁移到 v2待修正修正并复验后补入
EX-11/report/legacy 替代方案通过进指南
合计11 个示例通过 9 · 修正 2—
可以排除的「先发再修」「示例先随版发布、后面再补」可以排除——待修正的 2 个对应API 文档与代码同步巡检 台账里客户在用的示例失效项,错示例进指南等于把漂移从文档站搬进客户代码里。未验证示例不进指南,这条没有例外。
4

三受众材料分发 · 客户版 / 开发者版 / 客服版

6 家集成方按影响分三档,客服拿到预判问题清单
受众材料要点发送时点
客户版发布说明 · 客户摘要Added 8 高亮 + Security 单独说明发版当天
开发者版迁移指南 + 变更明细Breaking 弃期表 + 9 个已验示例发版前 2 天
客服版预判问题清单多币种咨询预案 + 弃期答疑口径发版前 1 天
把发布日翻译成钱客服拿到预判清单,发布日的咨询洪峰第一次有预案而不是临时抓人——6 家集成方里强相关 3 家先收开发者版(含华驿的迁移时间表),常规 3 家收客户版即可。分档通知省下的不是邮费,是每一家「收到看不懂的材料」之后打进来的那通电话。
IO

成稿 · 发布包三件套 + 验证记录 + 通知范围表

发布说明从此是漂移台账的下游,不是又一次考古
交付物格式状态
发布包三件套docx客户版 / 开发者版 / 客服版 · 含签发栏
迁移示例验证记录xlsx11 个 · 未验证不进指南
受影响集成方通知范围表xlsx6 家 · 建议发送时点
弃用时间表只出建议稿 · 正式承诺由人签发
这份发布包现在还不能直接签发:Breaking 项的 6 个月弃期是建议稿,写进客户通知的那一刻起集成方会按它排自己的年度规划——正式承诺由人签发。

方案一:下周二发版按全套走——周五 6 家集成方先收通知(强相关 3 家带迁移时间表),EX-09/10 两个示例修正复验后补入指南,内部零新增投入。

方案二:若把 2 个待修正示例直接随版发布——华驿按错示例写完迁移代码,返工加上联调窗口的占用,代价远超等两天修正复验;「先发再修」省下的两天,是用客户对文档站残存的信任付的账。
之后

这一次跑完,公司多了什么

不讲省了多久 · 讲少了几个隐患、沉淀了什么
✓
发布说明从「发完就算」变成三受众三份材料,changelog 与文档更新这两件事第一次被分开对待
✓
Breaking 变更拿到对照行业惯例的迁移期建议稿——弃期承诺有依据、可签发、可追踪
✓
迁移示例 100% 过验证关——金融级接口的示例质量第一次有了硬关卡
✓
客服拿到预判问题清单——发布日的咨询洪峰第一次有了预案而不是临时抓人

追问现场可能被问到的

答不上来的问题,比答得漂亮的问题更能决定这场演示的结果

发版频率高,每版都这么干会不会太重?
三件套的重量是弹性的:无 Breaking 的常规版,客户版与客服版可以合并成一页;有 Breaking 的版本才走全套——分级本身就是这套流程的一部分。
弃用时间表为什么只出建议稿?
因为它是承诺。写进客户通知的那一刻起,集成方会按它排自己的年度规划——建议稿给依据和区间,正式承诺由人签发,这条边界是信任的护城河而不是效率的负担。

想了解来龙去脉?

回到场景引入,看这个场景的痛点、做法与边界