你写的文档，别人只听到咚咚咚

你让一个写了十年代码的架构师，写一份系统设计文档。他写得很认真，画了架构图，标了数据流向，甚至还附了参考论文。

新人拿到文档，翻了两页，找你说：”每个字我都认识，但连在一起就像在看天书。”

你第一反应是不是”这新人基础也太差了”？

先别急着下结论。不是新人太笨，是专家太”聪明”了。

你脑子里有旋律，别人只听到”咚咚咚”

1990年，斯坦福大学做了一个有意思的实验。

实验很简单：一个人用手指在桌上敲出一首歌的节奏，让另一个人猜歌名。敲的人先预测：”对方大概能猜中50%吧。”

实际结果呢？猜中率只有2.5%。

为什么差这么多？因为敲桌子的人脑子里”听得到”旋律。他敲《生日快乐歌》的时候，脑海里自动补全了歌词、音调、和声，感觉节奏清晰无比。但坐在对面的人听到的是什么？”咚、咚咚、咚咚、咚——咚、咚咚、咚咚、咚”。一串毫无意义的敲击声。

这就是心理学家所说的”知识的诅咒”（The Curse of Knowledge）：一旦你知道了某件事，你就再也无法想象”不知道”是什么感觉。

写技术文档的时候，你就是那个敲桌子的人。你脑子里有完整的系统架构、有每个模块的设计意图、有踩过的坑和做过的取舍。你觉得自己写得清清楚楚，但读者看到的只是——咚咚咚。

专家坐电梯，新人爬楼梯

知识的诅咒具体是怎么害人的？我用一个比方来说。

专家思考问题，像坐直达电梯。从1楼到30楼，”叮”一声就到了。中间经过了2楼到29楼，但他根本没意识到这些楼层的存在——因为他已经走过太多遍了，大脑自动把中间步骤打包成了一个快捷方式。

但新人没有这部电梯。他得爬楼梯，一层一层上。2楼是”什么是微服务”，5楼是”服务之间怎么通信”，12楼是”为什么要用消息队列”，20楼是”分布式事务怎么处理”。每一层都是一个他需要理解的概念。

专家在30楼朝下喊：”上来啊，很简单！”新人在2楼仰头看，连电梯在哪都找不到。

这就是为什么很多技术文档读起来像是”中间少了什么”。确实少了——少了专家脑子里那些”理所当然”的中间步骤。他不是故意藏着掖着，他是真的忘了这些步骤的存在。就像你现在试试——你能想象自己不认识”A、B、C”是什么感觉吗？想不出来吧。恭喜你，你也被诅咒了。

等一下，这不是”表达能力差”的锅

说到这里你可能想反驳了：”这不就是表达能力的问题吗？写不好文档，说明这个人不会表达。”

还真不是。

你去观察一下身边那些在技术大会上讲得行云流水的人——台上金句频出，台下掌声雷动。回去让他写份文档？照样没人看得懂。能说会道和”知识的诅咒”是两码事。

打个比方。表达能力差，是”我想说苹果，但嘴笨说成了梨”。知识的诅咒是”我说了苹果，但我不知道你连水果是什么都没概念”。一个是嘴跟不上脑子，一个是脑子欺骗了自己。

这是大脑的一个出厂bug。为了运行效率，你的大脑会自动把熟练知识”压缩”。就像一个100MB的文件zip成了10MB，你打开毫无障碍。但你忘了一件事——别人手里根本没有解压软件。

你不是不会解释，你是忘了别人需要解释。

三个打破诅咒的技巧

好消息是，诅咒能解。坏消息是，解药有点反直觉——不是”提高表达能力”，而是学会”假装自己不懂”。

三个技巧，拿走直接用。

技巧一：”妈妈测试”

写完一份文档，找一个非技术人员读。可以是你妈，可以是你女朋友，可以是隔壁市场部的同事。让他读，你在旁边看。

不用让他全看懂——毕竟是技术文档。你只需要数一件事：他指着文档问”这是什么意思？”的次数。如果超过3次，说明你至少跳了3个台阶。

为什么要找外行？因为你自己检查不出问题——你脑子里会自动补全缺失的信息。但”妈妈”不会。她就是那个只能听到”咚咚咚”的人。她每指一处”听不懂”，就是你跳过的一层楼。目的不是让妈妈学会微服务，而是让你看见自己的盲区。

技巧二：先写结论，再写推导

大部分专家写文档的习惯是”我怎么想的就怎么写”：先说背景，再说调研过程，然后列出几个方案的对比，最后得出结论。

问题是，读你文档的人不需要重走你的心路历程。他只想知道：结论是什么？我该怎么做？

把结论放在第一行。”我们选方案B，用Kafka做消息队列。”然后如果他想知道为什么，往下看。不想知道？到此为止，他已经拿到了他需要的信息。

这就像GPS导航。你打开高德地图，它直接告诉你”走左边那条路”。它不会先给你讲城市路网规划原理、交通流量分析模型、再推导出为什么走左边比走右边快3分钟。

结论前置，推导后置。这一条改变，就能让你的文档的可读性翻倍。

技巧三：每个术语第一次出现时，用一句话翻译

你觉得”每个程序员都知道什么是API”，对吧？

不好意思，真不是。我带过的新人里，计算机专业毕业的，工作第一周分不清REST和RPC的大有人在。更别说那些从培训班出来的、半路转行的。

规则很简单：每个技术术语在文档中第一次出现的时候，花一句话解释它。不需要长篇大论，就一句话。

“我们使用gRPC（一种高性能的远程过程调用框架，可以理解为’让两台机器像调用本地函数一样互相调用’）进行服务间通信。”

就这么一个括号，新人的阅读体验就从”我是不是走错片场了”变成了”哦，原来是这么回事”。

你可能觉得这样做很啰嗦、很低级。但记住，你觉得”低级”恰恰是知识的诅咒在作祟。你已经在30楼了，你当然觉得解释1楼的东西是浪费时间。但对于那个正在爬楼的人来说，这句解释就是一盏路灯。

那份文档不是写得不好，是写得”太好”了

回到开头那个场景。

那份没人看得懂的系统设计文档，不是因为作者水平差——恰恰相反，是因为他太懂了。懂到大脑已经把知识压缩成了只有自己能解开的密码。

知识的诅咒并不可怕。可怕的是你不知道自己中招了。

但好消息是，你正在读这篇文章，说明你已经开始意识到这个问题了。这就是破解诅咒最难的一步——承认”我觉得显而易见的东西，对别人来说可能是天书”。

下次写文档、做分享、带新人的时候，别急着从30楼开始讲。先低头看一眼：对面那个人，现在在几楼？

真正的高手不是知道得最多的人，而是能回到1楼，陪你一起往上爬的人。