产品文档改版后,旧软文里的引用不能按“全部重写”或“全部不动”一刀切。判断依据是引用是否依赖被改动的字段、入口或术语:依赖核心字段的必须更新,仅作背景提及且语义仍成立的可以保留,但要加一句版本限定。先按引用类型分三档处理,再决定改文还是改链。
旧软文里的引用大致分三类。第一类是操作性引用,比如让读者在某个设置页填写某个字段名、按某个按钮完成配置。产品改版一旦改了字段名、按钮位置或步骤顺序,这类引用就从“能照做”变成“照着做会卡住”,必须更新。第二类是结论性引用,比如引用文档里的某条限制、某个默认值或某条兼容说明。只要文档改的是表述而非结论,旧文可以保留;如果结论本身变了,旧文就变成错误信息。第三类是背景性引用,比如开头一句“该产品支持批量导入”,这类引用对版本不敏感,通常不用改。
区分方法很直接:把旧文里的每处引用摘出来,问一句“读者按这句话去操作,会不会找不到入口或填错字段”。会,就归入第一类;不会但结论可能过时,归入第二类;都不会,归入第三类。这个分档是后续所有动作的前提。
当软文承担“引导读者完成一个动作”的功能时,它对文档的依赖最强。产品文档改版如果调整了导航层级、字段命名或默认选项,旧文里的截图说明、步骤编号、字段名都会失准。此时更新不是润色,而是重写操作段落。
具体动作:先打开改版后的文档,把旧文操作段落逐句对照,标出所有出现字段名、菜单名、按钮名的地方。然后只改这些标记点,保留旧文的论证结构和示例场景。改完后做一次“盲走”检查——假设自己只知道旧文,能否在改版后的文档里找到对应入口。找不到,说明还有漏改的引用。
这个动作的结果会直接影响下一步:如果盲走通过,说明这篇旧文只需局部替换;如果盲走失败且失败点集中在同一模块,说明该模块的文档结构变化较大,旧文可能不值得逐句修补,应考虑重写或合并。
不是所有引用都随改版失效。旧文引用文档里的某条限制说明、某个默认行为或某段背景介绍时,改版可能只是换了措辞。这种情况下,判断标准是“结论有没有变”,而不是“文字有没有变”。
操作上,把旧文引用的结论抄成一句话,再去改版后的文档里找对应表述。如果两句话在事实上一致,旧文可以保留,但建议在引用处补一个版本限定,例如“以当前文档版本为准”。如果结论已经变化,旧文必须改,且要检查同一结论是否在文中多处出现,避免只改一处留下矛盾。
这里有一个容易忽略的例外:旧文引用的结论虽然没变,但文档已经不再提这条结论。这通常意味着该结论不再是推荐做法,或已被新方案替代。此时旧文即便事实无误,也可能误导读者。处理方式是降级引用——不再把它写成操作建议,而是改为历史说明或直接删除。
假设某产品文档改版,把“高级设置”下的“同步频率”字段改名为“更新周期”,并把它从二级菜单移到一级菜单。手头有三篇旧软文:
这个例子的重点不是三篇文章本身,而是分档动作:先分类,再逐档核对,最后决定改文、改链还是保留。数字和字段名仅为说明假设的比较方法,不代表任何真实产品。
单篇旧文按上述方法处理通常有效,但旧文数量上去后会出现例外。第一种例外是同一引用在几十篇文章里重复出现,逐篇核对成本过高。此时应先在文档侧确认该引用的新表述,再批量替换,但替换前必须抽样检查,确认没有文章把该引用用在特殊语境里。第二种例外是旧文本身已经过时,与文档改版无关。这类文章即便引用更新了,整体价值仍然有限,不值得投入同等精力。第三种例外是引用指向的文档页面已被合并或下线,此时更新引用没有意义,应改为指向新页面或删除引用。
判断是否进入例外,可以看两个信号:一是同一处引用在多个页面重复出现,二是引用指向的文档地址已经变化。出现任一信号,就不要再按单篇流程处理,而是先统一引用口径,再回填到各篇文章。这个顺序能避免改到一半发现口径又变了。
改完引用并不等于结束。为了让下一次文档改版时能快速定位受影响范围,建议在更新旧文时记录三件事:改的是哪类引用、对应文档的哪个位置、改后是否做过盲走检查。记录不必复杂,一句话即可,例如“操作段字段名替换,已核对新入口”。这样下次再遇到改版,可以直接按引用类型筛选,而不是重新通读全部旧文。
如果旧文数量不多,也可以只维护一份引用清单,列出每篇文章依赖的文档字段或结论。清单的维护成本会随文章数量上升,因此规模较小时手工记录即可,规模较大时再考虑用脚本比对文档变更。选择哪种方式,取决于你能接受的核对频率,而不是某种固定标准。