替代方案的价值不在于证明旧产品还能用,而在于让读者在旧入口关闭前完成迁移。写法上应先给判断条件,再给可执行步骤,最后交代哪些旧内容保留、哪些下架。
假设一个情境:某工具团队停掉了旧版短信群发接口,但官网仍留着三篇调用该接口的教程。团队不确定是逐篇改写,还是整组下架。这个判断不能只看教程的访问量,因为访问量高也可能来自已经无法完成操作的用户。
可以按两个条件区分:
一个可操作的动作是:把每篇旧教程的第一段操作步骤暂时替换成一句状态说明,例如“此接口已停止受理新请求,现有配置请按下文迁移”。发布后观察读者是否仍在评论或工单中询问旧参数。如果询问量下降、迁移相关提问上升,说明状态说明起了作用,下一步再补迁移细节;如果询问量不变,说明读者没有读到提示,问题可能出在标题和摘要,而不是正文深度。
很多替代方案失败,是因为只写了“改用新方式”,没有写清楚旧动作对应的新动作。读者需要的是映射关系,不是新功能的介绍。
假设旧教程里有这样一段:
POST /sms/send,参数为 phone、text、send_time。
替代方案不能只写“请使用新版发送接口”,而应至少说明三件事:旧参数对应新参数中的哪一个;send_time 这类参数在新方案里是保留、改名还是取消;如果取消,读者应改用哪种做法。对于无法一一对应的部分,直接写“该能力已不再提供”,比含糊带过更省读者时间。
如果新旧方案并存一段时间,还要写清并存期的边界:旧方案在什么条件下仍可调用,新请求从什么时候起只能走新方案。这里不需要承诺具体日期,但必须给出判断依据,例如以控制台状态或公告为准。读者据此决定是立即迁移还是先并行验证。
旧教程并非整篇作废。发送频率控制、号码格式校验、退订处理这类与接口无关的段落,通常仍然成立,可以保留。需要改掉的是那些把旧产品当作默认前提的句子,例如“在旧版控制台创建应用后复制密钥”。
具体做法是逐段标注三类状态:
标注完成后,先处理第二类,因为它的读者最多、改造成本最低。第三类删除后,应在原位置留一句指向迁移说明的短句,避免读者从搜索或外链直接跳进来后失去上下文。这个动作的结果是:旧链接仍能落到有效页面,读者不会因为找不到原步骤而反复返回搜索。
旧教程的标题往往只描述操作,例如“如何用某接口发送短信”。停产后如果标题不变,读者点进来才发现不能用,跳出和再次搜索几乎必然发生。更合适的做法是在标题或摘要中直接体现状态,例如把“如何发送”改成“发送接口停用后的迁移步骤”。
这里没有通用的字数或关键词阈值。判断标准是:读者只看标题和摘要,能否知道自己面对的是旧方案还是新方案。如果两篇内容分别讲旧方案迁移和新方案接入,标题应让二者可区分,而不是用同义词互相替换。同义改写不会带来新的信息价值,只会让读者更难选择。
还有一个容易被忽略的动作:检查正文里的内部链接。指向旧教程的链接如果还写着“点击这里查看接入方法”,应改成“查看迁移步骤”或“查看已停用接口的说明”。链接文字的变化会影响读者预期,也影响他们是否继续往下读。
改完一篇后,不必立刻批量处理全部旧教程。可以先选访问最集中、且旧接口依赖最深的一篇做验证。验证时看三类信号:读者是否仍在询问已删除的参数;迁移步骤是否在关键处被追问;页面是否还被外链当作“仍可用”的依据。
如果第一类信号减少,说明状态说明有效,可以按同样结构处理其他篇目。如果第二类信号集中出现,说明替代步骤缺少某个判断条件,应先补这一篇,再推广。如果第三类信号出现,说明问题不在正文,而在外部引用和旧入口,需要另外处理链接和跳转说明。这个顺序能避免一次性改完几十篇后才发现方向不对。
替代方案的终点不是把旧内容全部重写,而是让读者在旧方案退出后仍能完成原目标。保留可复用的规则,替换失效的动作,明确说明无法替代的部分,这三步做到,教程才算真正完成迁移。