发布前先写迁移说明：用户下一步比创始人故事重要

产品要改，先别急着发公告。先把迁移说明写出来，念一遍。谁受影响、什么会失效、怎么迁到新行为、迁失败了怎么办——这四件事说不清楚，说明发布还早。

公开构建会让改动被更多人看见。围观的人好奇你在做什么，另一部分人则真的依赖现有行为。一份好的说明要同时照顾这两拨人，而且受影响用户的下一步动作，优先级高于创始人的发布故事。

先找“人依赖什么”，别先看代码改了什么

起点是当前的工作流，不是实现层的差异。数据库改一列，用户可能毫无感觉；导出文件里一个不起眼的变化，却可能打断某个人精心维护的导入流程。

把“今天能做什么”和“发布后能做什么”逐条写下来。默认值、权限、已保存的设置、文件格式、集成关系，在相关的地方都要覆盖。这些条目是用来做影响检查的提示，不代表每项改动都会波及全部。

接着问：谁在依赖旧行为？证据可能来自支持对话、文档，或者获得授权的产品记录。不知道就明说不知道，先查清楚，再判断这次改动是否无害。

功能使用率低，不等于没人依赖。一个月才用一次的导出功能，对那个每月用一次的人来说，可能就是天大的事。

变更日志和迁移说明是两回事

Keep a Changelog 提倡为读者维护一份经过整理的记录，明确包含新增、弃用和移除。这是有用的基础，但一份变更清单在读者需要动手时，仍然需要配上操作说明。

变更日志告诉读者这个版本改了什么；迁移说明告诉读者怎么保住、或者有意改变现有的工作流；创始人的公开更新再去解释原因和取舍。三份东西可以互相链接，不必重复每个细节，但真正的操作步骤要有一个持续维护的唯一位置。把唯一一份可能还需要更正的说明放在社交帖子里，是个糟糕的选择。

如果已知有一群人会失去什么，就别把改动说成对所有人都是改进。哪怕新设计对产品的主要场景更友好，也要把受影响的行为直白写出来。

拿一个虚构的 CSV 迁移练一遍

设想一家虚构的排期 SaaS，提供预约数据导出。现有导出把客户显示名放在第一列；计划中的导出会在最前面加一个稳定的预约标识，把名字挪到第二列。

听着很小，直到某个现有表格把第一列当名字读。创始人如果只测“新文件能不能下载”，就会漏掉这个断掉的交接点。

迁移说明要圈出受影响的人群：那些靠位置选择字段的已保存导入。要解释新布局，附一份用虚构数据做的示例文件，还要把这类人和“每次手动打开导出文件”的读者区分开。这是个示意场景，不是关于某家真实公司或真实客户系统的报告，目的只是展示：一条公开公告可以准确描述功能，却仍然漏掉用户最重要的那件事。

用同一个例子跑旧路和新路

准备一个能走通旧流程的例子，存下预期结果。然后用等价的虚构输入走一遍新流程，在接收端检查结果。

排期例子里，真正的终点是一张填对的表格，下载完成只是中间步骤。名字、标识、时间、空值，是否都落在文档所说的位置，要逐一核对。保留一条旧流程不变的对照路径，才能分清问题是迁移引入的，还是例子本来就有的。

记录你查了什么、没查什么。一个表格软件、一个导入器，只是有边界的测试，不能证明所有下游工具都接受新格式。

写到读者不用问你就照做

第一个动作之前，先说清起始条件：这套说明适用于哪个账号、哪个导出版本、哪种已保存设置。

然后按用户实际操作的顺序写步骤，用界面上真实可见的名称。如果某一步需要一个还没实现的选项，说明这份说明已经帮你找到了没做完的活。

改完要有检查动作。“导入一个示例，确认名字落在名字字段里”，比“确保一切正常”有用得多。读者得能在依赖输出之前，自己发现迁移失败。

找一个不熟悉这次改动的人，对着测试环境读一遍说明。哪个步骤需要你口头补充，就回去改文字。只有真的做了这次评审，才能说它完成了。

迁移失败怎么办，得先定下来

有用的说明需要一条产品真能支撑的退路：退回旧格式、暂时保留旧工作流，或者在继续之前走一条明确的支援通道。

别为了让公告听着安心就承诺回滚。有些改动在新数据写入之后，没法干净地逆转。把真实边界写出来，并且在发布说明之前就把实现决策定好。

那个虚构的导出里，创始人可以选择保留原布局为默认、把新布局单独提供。这只是一种可能的设计，不是普遍要求。另一种做法是精心公告的替换，配一段清晰的过渡期。选哪个，取决于证据、同时维护两条路径的成本，以及对依赖旧行为的人的影响。

用户动作放前面，创始人故事放后面

公开发布帖的开头就写受影响的行为和需要做的动作，把持续维护的迁移说明链接放在读者一眼能找到的地方。等读者知道该干什么了，再解释原因——比如稳定标识解决了反复出现的导入问题。别把内部清理包装成客户收益，除非你把其中的关联讲清楚。

可用性要小心。提前写好的发布说明，不能暗示新行为已经上线。访问权限因版本或人群而异时，说清楚谁能用。

截图能展示新的导出选项，但证明不了现有导入器还能用。截图用来解释界面，演练用来评估工作流。

把迁移说明分享给相关同行，能暴露遗漏的假设。有人可能发现说明里没提时区、已保存的字段映射，或者空字段怎么处理。同行评审和真实目标用户的检查是互补的：另一个开发者可能懂格式，却不懂某个业务特有的依赖，描述评审结论时要把这个区别摆明。也别让人往公开帖子里上传私有导出文件，给一份虚构示例，再给一条不暴露真实客户信息的报错路径。

发布之后，让迁移说明和它描述的版本保持绑定。发现漏掉的情况，就补一条带日期的更正，说明实际影响。如果更正改变了用户的下一步动作，要回到公开公告那里指路，让存了第一条帖子的人能找到当前说明。翻支持报告时，既要找缺陷，也要找误解——技术上正确的改动，也可能因为说明假设了读者并不具备的环境而失败。

下一次公开发布之前，试着先写迁移说明。难写的那一段，往往指向难做的过渡。把过渡解决了，你手里才有更值得公告的东西。