先给结论:产品文档改版后,旧文章里需要更新的不是所有提到该产品的句子,而是那些把旧文档当作“唯一依据”来支撑判断的引用。具体说,凡是引用旧文档中的参数、入口名称、限制条件、操作顺序,并据此告诉读者“该怎么做”的地方,都必须核对;只是顺带提到产品名、不依赖文档细节的段落可以不动。下面从一个常见矛盾现象切入,说明两种解释,再给出能区分它们的证据。
产品文档改版后,编辑常遇到一种情况:明明知道文档变了,但翻旧文章时觉得“每句都还挺对”。原因往往不是文章真的没问题,而是旧文章用的引用方式把变化藏起来了。
典型表现是:文章里写的是“在设置里打开某开关”,而改版后这个开关换了位置或改了名称;读者照着做找不到,但编辑自己看文字时,因为脑子里记得旧界面,反而读不出错。这类问题不会在“产品名是否还叫这个”的层面暴露,只会卡在动作指向上。
面对“旧文章看起来没错、实际却误导读者”的现象,有两种解释,需要分开对待。
改版动了旧文章引用的那部分事实,比如参数默认值、功能名称、权限限制、步骤先后顺序。文章本身没写错,只是它忠实引用的旧版信息已经失效。这种情况下,要更新的是被引用的具体事实。
文章没有引用具体事实,而是用“根据官方文档”“按说明操作”这类笼统说法带过。文档改没改,文章都不受影响,但也都不提供可核对的信息。这种情况下,要更新的不是事实,而是引用方式——把它改成能被验证的具体指向,或者干脆去掉依赖文档的表述。
两种解释对应的动作完全不同:前者是逐条核对事实,后者是重写引用结构。混在一起处理,就会出现“改了半天还是不知道改对没有”的消耗。
要判断某处引用属于哪种情况,可以用一个可操作的动作:把旧文章里每一处涉及产品的引用单独摘出来,脱离上下文,看它能否被当前文档直接证实或证伪。
这个动作的结果会直接影响下一步:摘出来能证伪的,进入事实更新队列;摘出来无法验证的,进入引用重写队列。两条队列的处理顺序不同,事实更新要跟着文档版本走,引用重写可以独立进行。
假设某产品文档改版,把“导出数据”从设置页移到了列表页的操作菜单里。旧文章里有两处相关表述:
用摘取法看第 1 处:它是一句可核对的动作指引,当前文档显示入口已变——属于解释一,必须更新,否则读者按步骤找不到入口。看第 2 处:它没有给出任何可核对的动作,文档改不改都不影响这句话的对错,但也帮不到读者——属于解释二,可以改写成具体指向,或者删掉。
这里的关键不是“文档改了所以要全改”,而是先分清哪处引用承担了判断依据的角色。承担了判断依据的,改版后必须核对;只是装饰性提及的,可以留到常规维护时再处理。
即便确认某处引用属于解释一,也不一定要立刻全文重写。可以按引用对读者决策的影响程度排序:
这个取舍的依据是读者的实际动作,而不是文章看起来是否“完整”。把有限精力放在会让读者操作失败的地方,比追求每处引用都同步更有效。
把上面的判断整理成一个可以重复执行的顺序:先摘取,再分类,后取舍。
执行完这一轮后,再遇到文档改版,复查范围就能从“整篇文章”缩小到“记录了依赖章节的那些引用”,后续维护的判断成本会明显下降。