用文字说服 — 让设计文档和RFC获批的结构

引言 — 一份写了三周的文档,只收到两条评论

花三周时间调研、跑基准测试,写出一份十二页的设计文档。分享出去,收到两条评论。一条指出了错别字,一条说"学习了"。两个月后,决定还没有下,这份文档变成了只能靠搜索才能找到的东西。

有过这种经历的人,通常会得出"我们组织不看文档"的结论。这话说对了一部分。人们确实不看文档。但这不是某个组织特有的毛病,而是所有组织的基本条件,而建立在"不会被读"这一前提上写出来的文档,和没有这个前提写出来的文档,通过率是不一样的。

这篇文章写给那些需要写设计文档、RFC、提案书、事故复盘建议之类需要获批的文字的人。前两篇讲说服的结构和处理反对意见的文章,处理的是对话场景;这一篇处理的是作者本人不在场的场景。

决定优先 — 把决定放在最前面,而不是心路历程

工程师写的文档,绝大多数都是按照自己解决问题的顺序来组织的:背景、现状调研、对比实验,最后才是结论。这是作者自己抵达理解的路径,不是读者需要的路径。

要解释为什么这种情况反复出现,"知识的诅咒"是一个很贴切的说法。这是科林·卡默勒、乔治·罗文斯坦、马丁·韦伯在1989年的论文中命名的概念:一旦知道了某件事,人就无法再想象不知道它是什么状态,即使装作不知道对自己更有利,也做不到把那份信息剥离出去。

这个概念最常被引用的通俗案例,是伊丽莎白·牛顿1990年的敲击实验。一个人用手指敲出一首熟悉歌曲的节奏,另一个人猜歌名;敲击者预测对方大概能猜中一半,实际的正确率却只有2.5%左右。不过,这里有必要诚实地说明一句:这项研究是一篇博士论文,通过大众读物才广为流传,很难说是一个反复被验证过的结果。 与其引用具体数字,不如把它当作一个比喻来用。这个概念本身——知道的人会系统性地高估不知道的人能理解到什么程度——确实在不少领域中被观察到过。

实务上的处方很简单。在第一段里放进三样东西:请求批准什么决定、什么时候之前需要、这个决定会带来什么改变。标题也要写成决定,而不是主题。不要写"缓存策略评估",要写"提议在读路径中引入缓存层——请于8月15日前批准"。打开通知列表时,点开它的理由必须已经写在标题里。

亚马逊是在组织层面强制推行这种结构的著名案例。2004年,它在高管会议上禁止使用幻灯片,改为要求提交六页的叙述性备忘录,会议以全员静默阅读20到30分钟开场。当时给出的理由是,叙述性的句子会暴露出幻灯片能够遮掩的逻辑漏洞。用要点罗列,条目之间的关系和相对重要性就会消失。用完整句子写,就必须用上"因此""然而"这样的词,而那一刻,论证中的漏洞会先被自己看见。

展示被否决的替代方案,才是提案区别于广告的标志

一份只包含一个选项的文档不是提案,而是广告。站在读者的角度,这种文档不是在请求批准,而是布置了一份作业——因为读者得自己去搞清楚还有哪些其他选项。

用格式来强制做到这一点的,是架构决策记录(ADR)。它有背景、决策、状态、后果四栏,后果一栏不仅要写好处,也要写清楚这个决定会让你不得不承受什么。RFC模板中的"替代方案"一节,目的也是一样的。

上一篇引用过的奥基夫1999年元分析,在这里同样适用。提出反对论据并作出回应的信息,在可信度和说服力上都优于单面信息(42项研究,d = 0.16);只提出反对论据却不回应的信息,表现反而不如单面信息(65项研究,d = -0.10)。把"替代方案"一节当成走过场来填,是要吃亏的。

好好写一个替代方案,只需要三行。第一行说这是什么。第二行说在什么条件下它才是正确答案。 第三行说在我们的条件下为什么不是。第二行是关键。没有它,只写第三行,就变成了先立一个稻草人再打倒它,而这一点,读者大多能看出来。

举个例子:

引入第三方认证服务。如果团队规模小、审计要求是标准化的,这几乎总是更好的选择。但在我们的情况下,内部审计日志要求的是按会话保存原始记录,而不是按用户保存,我们评估过的三家服务商都不支持这种形式。

还建议再加一节:"如果这个提议是错的,原因会是什么"。在这里写下自己回答不了的反对意见。看起来像是在削弱信任,实际上恰恰相反,更重要的是,这能防止那个反对意见在批准之后变成一次事故。

把"什么都不做"的成本变成数字

大多数提案论证的都是"做了这件事会变好"。但决策者实际比较的对象不是别的提案,而是维持现状。而维持现状这一边的成本,没有人会写出来。于是默认选项获胜。

现状偏差本身,自萨缪尔森与泽克豪泽1988年的研究以来,已经在多个领域被反复观察到。但把它自动归因于损失厌恶这种常见解释,近来受到了相当大的质疑。戴维·加尔与德里克·拉克在2018年的论文中指出,"损失通常比等量收益的影响更大"这一说法目前证据并不充分,且高度依赖具体情境,此后也出现了针对这一质疑的反驳。所以,"人对损失的感受是收益的两倍,所以要用损失框架来写"这类建议,现在引用是有风险的。不如只写一件简单得多的事实就够了:如果比较对象没有出现在文档里,比较就不会发生。

把什么都不做的成本写成三个数字。

第一,现在每周正在流失的东西。等待时间、值班呼叫次数、手工操作耗时、回滚次数——只要是已经在被测量、或者能从日志里提取出来的,就足够了。第二,这个数值的趋势。把六个月前的值和现在的值并排放在一起,这件事本身就是一种论证。第三,拖得越久事后代价会变得多大。如果需要迁移的对象每个月都在以某个百分比增长,那个数字本身就是拖延的利率。

这里要提醒一个常见的失误:在造不出数字的时候硬造一个。一个没有依据的投资回报率估算,会把整份文档的可信度一起拖下去。遇到这种情况,不如这样写:

这项成本目前尚未被测量。两周内可以加上埋点,这是本提案的第一步。如果测量结果低于每周5小时,后续步骤就不再推进。

为浏览者而写

文档不被批准的原因,很大一部分是因为它没有被读。尼尔森诺曼集团的视线追踪研究报告称,用户平均只读一页中20%到28%的文字,2006年首次描述的F形扫描模式已经被反复观察了近二十年。虽然这是网页内容的研究,但没有理由认为,一个在会议前五分钟才打开文档的决策者,读得会比这更认真。

所以,一份需要被批准的文档,实际上必须同时是两份文档:一份30秒版,一份30分钟版。而那份30秒版不能只塞进一个摘要小节里,它必须分散在整篇文档中。

具体的做法有四条。

把小标题写成句子,而不是名词。不要写"性能分析",要写"78%的读取延迟来自单一查询"。如果只读目录就能明白论点,这份文档对浏览的人也是有效的。

把结论放在每段的第一句。F形模式之所以会出现,是因为人们只读每段的前半部分就往下翻。如果一段是从论据开始、以结论收尾,那个结论就不会被读到。

表格只用来做比较。表格是抓住视线的强元素,把非比较性的内容做成表格,会把读者的注意力消耗在不重要的地方。

每节最多加粗一处。加粗三个地方,效果等于没有加粗。论证也不要用要点罗列来写。要点罗列只有在条目真正并列时才是诚实的,一旦证据之间存在因果或条件关系,要点罗列会把这层关系抹掉。这和亚马逊禁止幻灯片的理由完全一样。

在你不在场的会议室里被传递的那个段落

实务中最重要、却几乎没人训练过的一点是这个:你的文档会在你不在场的会议上被引用。 你的主管会把它带进他上一级的会议,别的团队的人会把它复制粘贴到自己的频道,半年后有人会通过搜索找到它。到那时候,活下来的不是整份文档,而是一个段落。

那个段落需要满足四个条件。

它必须脱离前文也能成立。"上面提到的方式""这个问题""对应的组件"这类表达一旦出现,一被截取就会失去意义。要用专有名词和具体的对象名称。

数字和日期必须就在这个段落里。引用它的人不应该还要再回去找一遍。

诉求必须包含在里面。如果只剩下情况说明,那么无论它被引用到哪里,都不会发生任何事。

长度要控制在两三句话。超过能被复制粘贴的规模,它就不会被引用,而是会被概括。一旦被概括,你就失去了对它的控制权。

这里还可以再加一点:用同样的形式重复同一句话。"被重复呈现的陈述会被评价为更可信"这一现象,在说服文献中算是经受住复现检验、相对站得住脚的发现之一。德申团队的2010年元分析综合了51项研究,报告的效应量在d = 0.39到0.50之间,最近一次大规模再综合在校正了小样本偏倚之后,依然保留了g = 0.37。实际的含义是:不要每次写文档都把措辞重新打磨一遍。每次都换一种说法,重复带来的好处就会消失,组织里也会因此漂浮着好几个彼此略有差异的版本。

边界也要写清楚。这种效应并不区分陈述的真假。所以重复不是一种技巧,而是一种责任。只应该重复自己已经核实过的句子,而一旦后来发现是错的,就要用同样的力度反复纠正。

把一段薄弱的提案重新写一遍

这是一种经常能看到的开篇段落形式。

目前我们的认证模块存在不少问题。遗留代码较多,测试覆盖率也低,最近维护难度也在不断上升。团队内部对需要改进这一点已有一定共识。据此,我们提议对认证模块进行整体重构。详细内容如下。

语法上没有问题,读起来很用心,但什么都推动不了。数一数缺了什么:没有请求任何决定——"我们提议"不是在请求一个决定。没有一个数字。"问题很多"这句话无法被反驳,但同时也不提供任何信息。没有写"什么都不做"的成本。没有考虑过的替代方案。没有截止日期。而且一旦脱离上下文被截取出来,根本看不出这是哪家公司、哪份文档里的段落。

把同样的内容重新写一遍。

请求批准从8月第三周起,用三周时间替换认证模块中的令牌校验路径。过去六个月发生的12起事故中,有5起源于这条路径,这5起事故的平均恢复时间为47分钟,是其他领域平均值的两倍。如果现在不处理,9月的社交登录功能开发将再次触碰同一段代码,到那时需要撤销的范围会翻倍。我们也评估过全面重写和引入第三方认证服务这两个替代方案:前者需要四个月以上,后者无法满足内部审计日志按会话保存原始记录的要求。失败标准很明确:如果三周内现有的集成测试无法全部通过,就回滚,9月的开发工作将在现有代码基础上进行。

一段话里塞进了六样东西:请求的决定和期限、最有力的证据——实测数据、什么都不做的成本、两个被否决的替代方案及其理由,以及失败标准。无论复制粘贴到哪个会议上,单凭这一段就能作出判断。

篇幅变长了。这笔交换在大多数情况下是划算的。短文档会被读完,完整的段落才会被拍板。如果是需要在会议上用口头方式说服对方的场合,系统设计面试准备一文中讨论的口头讲解结构值得参考。

文档中真正管用的招数

这八条没有一条要求文笔。全部都是关于放在哪里、写不写进去的判断。用文字说服人的能力,大部分不在于文采,而在于判断什么该放在哪里。

结语 — 让批准比撤销更便宜

用文档说服人,不是要改变读者的想法。而是要把提议本身设计成:批准的风险看起来比不批准的风险更小。 由提议者自己先写下失败标准、写清楚回滚方法、把自己回答不了的反对意见摆出来——这些做法全都朝着这个方向起作用。

希望你在下一份文档里只改两件事:把第一段改成用请求的决定开头,以及做出一段脱离上下文也能成立的话。剩下的事,等这两点站稳了之后再加也不迟。