产品文档改版后,旧文章里需要更新的引用不只是失效链接。判断标准是:被引用的概念、参数、入口、限制条件是否已经改变,以及读者按旧引用操作是否会产生错误结果。先按引用类型分级,再决定改、删、跳转还是保留并加说明,能避免一次性重写全部旧文,也能防止遗漏真正影响用户决策的引用。
把旧文章中的引用逐条标出来,按下面四类处理。这个分类决定了更新优先级,也决定了你接下来要动正文还是只动链接。
实际操作时,可以先把旧文章复制到表格里,逐段标注引用属于哪一类,再记录旧文档中的原话和新文档中的对应表述。这个动作的结果是:你能看出哪些引用是“读者会照着做”的,哪些只是“读者可能点开看”的,前者优先处理。
不是所有引用都要同步更新。对每条引用问三个问题,只要有一个答案是肯定的,就应进入修改队列。
如果三个问题都是否定的,例如只是指向一篇仍然保留的扩展阅读,可以暂时保留,但要记录复查时间。这样做的结果是:更新工作量集中在真正影响用户动作的引用上,而不是把整篇文章推倒重写。
假设你有一篇旧文,其中一句是“在设置页的高级选项中开启自动同步”。改版后该选项移到了“数据与同步”页面,并且默认开启。此时旧引用属于操作性引用,读者按旧路径找不到入口,必须改。若另一句只是“关于同步机制,可参阅产品文档”,而该文档仅换了文件名,则属于导航性引用,替换链接即可,不必重写整段。
很多旧文的问题不在链接,而在链接周围的说明。只把旧地址换成新地址,读者仍然会按旧描述理解新文档,产生新的误导。
处理一条操作性引用时,按这个顺序做:先在新文档中找到对应段落,确认入口、字段和默认值;再把旧文中的路径描述改成与新文档一致的表述;最后检查上下文有没有依赖旧路径的举例、截图说明或注意事项。这个动作的结果是:链接和正文说明同时对齐,读者不需要在新文档里二次猜测。
对于定义性引用,如果新版文档改了术语,旧文首次出现该术语时应使用新名称,必要时在括号中保留旧称,方便已有读者对应。不要全文机械替换同义词,那不会带来新的信息,反而可能让旧文与新版文档的表述脱节。
改版后,有些旧引用指向的内容被合并或移除了。这时不要一律删除,先判断它在旧文中是否还有独立价值。
这个取舍的结果是:旧文不会因为一次改版而变成链接废墟,也不会保留已经与官方口径冲突的旧说法。
全部改完后,从旧文中随机抽三段,分别对应定义性、操作性和约束性引用,按读者视角走一遍。检查点包括:链接是否指向新版文档、正文描述是否与新版一致、有没有残留旧术语或旧路径。若抽样中发现同类问题反复出现,说明前面的分类或替换规则需要调整,应回到引用清单重新处理,而不是只修补抽到的段落。
复查通过后,把这次改版涉及的引用变化记录在更新日志中,注明哪些文章已处理、哪些引用是保留观察。这样下一次产品文档再变化时,你可以直接从日志出发,而不必重新通读全部旧文。