说明书是最谦卑也最难写的文体——没人会夸一份好用的操作指南,但一份坏的能让整个团队卡在同一步。它不追求文采,只追求一件事:让一个不在你脑子里的人,照着做,做对。技术人写的 README、API 文档、runbook、onboarding 手册,本质都是它。本期借四位真正研究「怎么教人做事」的人,把它写到「不用问就会」。
说明的最小单位是「一个可执行的动作」。把连贯的散文拆成编号步骤,每步只做一件事,用祈使句(动词打头)。关键在于——把条件、位置、目的写在动作之前,别让读者先动手,再发现原来有前提。
读者读说明不是为了欣赏,是为了「边读边做」。他们的注意力像激光,只盯着「下一步按哪」。于是两条铁律:一,动作要短到能被扫读抓住——编号列表加动词打头,远快于一整段「首先…然后…接着…」;二,因为读者一读到动词就抬手,任何前提(先备份、仅限管理员、生产环境别动)必须抢在动作前面说,否则等于事后诸葛。
拿你写过的一段安装或配置说明,改成编号步骤:每步一个祈使句、动词打头,所有前提和警告提到对应动作之前。数数原来有几个「先…其实要更早做」的坑。
思考题:你上次照别人的文档卡住,是卡在「没写」,还是「顺序错了」?
你(作者)脑子里有一套系统如何运作的完整模型;读者没有。他能看到的界面、命名、文档,是他唯一的信息来源(Norman 叫「系统映像」)。好说明的任务,是通过这个映像,在读者脑中装一个够用、能预测下一步的模型。
这解释了「照着做还是不会」的根源——纯步骤只给了 rote(死记),没给 model(模型)。读者一旦碰到文档没覆盖的情况就抓瞎,因为他不懂「为什么」。所以最好的说明会在关键处补一句「因为」:不是解释每个细节,而是给读者一个心智支点,让他能自己推断没写到的情形。这也是「知识的诅咒」的解药——你太懂系统,忘了读者是一张白纸。
找你文档里一句纯操作指令,补一句「为什么/它其实在做什么」,让读者能据此推断一个你没写的相邻情形。
思考题:「给模型」和「保持简洁」会冲突吗?哪一句「因为」值得留,哪一句只是你想炫技?
说明高手不满足于「写清怎么做对」,还会主动想「读者最可能在哪做错」,然后在那一步之前设一道防线——警告、约束、安全默认、验证步。比一句好报错更好的,是让那个错根本没机会发生。
报错是事后补救,预防是事前拦截,成本差一个数量级。对写文档的人,「错误预防」有具体动作:一,标出危险动作(这步不可逆/影响生产),并用视觉把警告与正文分开;二,给出安全默认("无特殊需求,保持默认"),省掉读者做他没能力做的决定;三,把隐性前提变成显式检查项。Norman 把这类设计叫 forcing function(防呆)——文档里的对应物,就是让读者「想犯错都难」。
拿一份含「危险动作」的操作文档,为每个不可逆步骤加三样:一句具体后果的警告(提到动作前)、一个安全默认、一个「怎么确认成功」的验证步。
思考题:文档做错误预防,和产品直接用设计(禁用按钮、二次确认)做预防,边界在哪?哪些根本不该让文档兜?
人不读说明书,只想赶紧上手。极简主义(Carroll)不是写得少,是砍掉一切挡在「读者开始行动」之前的东西——冗长铺垫、显而易见的解释、面面俱到的选项——只留能让他立刻动手、且出错能自己爬出来的最小集合。
为什么「少」反而更好用?因为读者的耐心是稀缺资源,每句废话都在消耗它,让他更可能放弃、转而乱试。Carroll 的反直觉发现是:给新手更厚的手册,他们学得更慢——厚手册推迟了动手。极简的三个动作:砍掉 happy-talk 式引言("欢迎使用…本工具旨在…"),直接给第一个动作;砍掉读者已知的(别解释什么叫"点击");把「完整」让位给「够用」——覆盖 80% 主路径,边角情况链接出去。
拿你一份 quickstart,用 Krug 法则删两轮字(先删一半,再删剩下的一半),删到读者能在读完前就开始做第一步。检查:有没有真的丢信息?
思考题:「极简」和「完整」在什么场景必然冲突?给外科医生的核查表 vs 给用户的 App 引导,边界一样吗?