选择与主题相符的示例,判断标准不是“例子好不好看”,而是它能否替读者完成一次具体验证:读完例子后,读者能对照自己的页面,判断某处该改还是不该改。对已有页面或项目做改进时,建议从交付结果倒推:先写清这次改完要得到什么可验收的结果,再决定需要哪些示例、由谁提供、谁核对、按什么条件判定合格。凡是无法指向页面具体位置、无法被第二个人复核的例子,都不适合放进正文。
从交付结果倒推,第一步是把“改进”翻译成可检查的句子。例如目标不是“内容更丰富”,而是“页面第二段补充一个与主问题直接对应的操作步骤,读者照做能得出一个明确结果”。这句话定下来后,示例的取舍就有依据:能支撑这个步骤的留下,只起装饰作用的删掉。
可以按下面的顺序整理资料:
责任划分也要跟着结果走:谁写示例,谁核对事实,谁确认它和主题一致。核对人最好不是写示例的人,因为写的人容易默认读者知道自己省略了什么。
拿到一个候选示例,可以用三个问题快速筛选。任意一项答不上来,就说明它和主题的关系还太松。
举个假设例子:页面主题是“已有文章如何补一段操作说明”,候选示例是“某篇文章增加了步骤后更清晰”。这个例子指向不明、无法复现、区分度也低。改成“页面第二段原本只写结论,现补上三步操作,并注明每步的完成标志”,就能被核对,也贴合主题。
同一主题下,示例类型的选择取决于读者要做的动作,而不是取决于哪种写法更流行。可以按下面的条件判断:
如果页面已有内容只是表述模糊,优先补步骤示例;如果读者反复问“该选哪个”,补对比示例;如果问题集中在操作失误,补错误示例。一次改进只处理一类问题,示例才不会互相打架。
示例写完后,按清单逐项核对,比通读一遍更可靠:
核对时区分“可能原因”和“已经确认的原因”。示例里出现现象解释时,如果只做了推测,就写成待验证项,不要写成结论。这样读者照做后若结果不同,也知道该回到哪一步检查。
下一步,挑出页面中最模糊的一段,按上面的检查项给它配一个可复现的示例,并让另一个人只看示例判断它对应哪一段。对方判断对了,这个示例才算通过。