writing-to-explain

name	writing-to-explain
description	写任何目的是让另一个脑子建立理解的东西时触发——教程、使用说明、科普、技术博客、README、SKILL.md、给 AI 读的指令文档、解释型随笔、架构说明、onboarding 材料。关键判断：输出要在读者（人或 AI）脑子里建立对某件事的真正理解，而不只是罗列事实或列举规则。写给 AI 的流程指令、skill 内容也适用——把 AI 当聪明的学徒来教而不是当执行引擎来命令，它遇到没覆盖到的情况才能用原则推断。不适用于严格的参考资料（API 字段表、schema 定义、参数列表）。

writing-to-explain

能把复杂的东西讲得让人看懂的作者——费曼、Paul Graham、Julia Evans、Polya、Carl Sagan——脑子里都有一个共同的姿态：

我懂的这件事，读者不懂。我的活不是展示我懂了什么，而是用读者脑子里已经有的材料，在 TA 脑子里搭一个差不多的理解。

这是翻译者的姿态，不是讲台上的姿态。翻译者脑子里装着两端——原文的含义和目标语言读者能接住的表达——两端之间搭桥。AI 默认只顾一端：它把自己脑子里的知识结构工整地铺出来（完备、分类、列规则、给正反例），然后就完了。读者看完脑子里其实没建起那个理解，因为没人帮 TA 搭桥。

下面几节讲大师们搭桥时具体在做什么动作。

从读者已经在的地方开始

费曼讲物理，第一句不是"力等于质量乘加速度"，是"想象你手里拿着一杯水……"。Paul Graham 写创业随笔，开头不是"创业公司是……"，是他上周跟朋友吃饭时冒出来的一句话。Julia Evans 写 debug，开头是"昨天我遇到了一个奇怪的 bug"。Sagan 讲宇宙，开头是"如果你把地球 46 亿年的历史压缩成一年……"。

他们都从读者生活里的场景或具体事件切入——不是因为懒得写定义，是因为读者需要一个锚点，新概念才挂得上去。话题的形式起点（定义、分类、历史背景）通常不是读者的锚点，是这个领域内部的约定起点。

具体动作：动笔前问自己"读者翻开这篇文章之前，脑子里最相关的那件事是什么？"——从那件事开始写第一段。

类比取自读者的生活，不是领域内的另一个概念

AI 最爱的类比是"X 好比 Y"，但 Y 往往是另一个技术概念。比如"promise 好比 future"——读者不懂 promise 的时候也不懂 future，这个类比没搭桥，是平移。

费曼式的类比是"X 好比你早上刷牙时发生的那件事"。从技术领域拉一个类比到日常生活，作者要多做一步——把概念抽象出来再找到日常里结构类似的东西。这一步是作者的功课，AI 默认绕过它。

好类比不追求精确，追求够用。"原子像小太阳系"不精确，但帮读者先建起一个可用的模型，后面再修正。差类比一上来就追求技术精确，读者反而建不起任何模型。

沿着"发现的路径"写，不是"展示的路径"

教材按最终的知识结构组织——定义 → 性质 → 推论 → 例子。这是展示的路径。

大师按发现的路径写——"我一开始以为是 A，后来发现 B 这个现象 A 解释不了，所以改成 C"。读者沿着这条路走，会产生每一步都自己想通了的错觉。这个错觉是好的，它就是理解本身。

Polya 的《怎样解题》整本书都是这样——不直接给答案，问你几个问题，你沿着问题走就自己走到答案。写解释型文章时偶尔插一句"这里你可能会想问……"然后自己回答，是同一招的简化版。

不要躲在术语后面

每个技术术语第一次出现时，在旁边用大白话赚一次权利——"这里说的 X，意思是……"。赚不到权利的术语说明作者自己也没想清楚，就该换词或者拆成几句话讲。

Julia Evans 的图文博客经常一整页就在拆一个术语。这个拆的过程是写作的主要动作，不是顺手的脚注。

自检：把写出的每个技术词圈出来，问"这个词我之前用白话讲过吗？"没讲过，要么讲一下，要么换掉。

别自己造压缩复合词

AI 写中文的时候有个很深的坏习惯——爱把一句话压成一个四字词或两字自造词：办砸 → 翻车、做完 → 收口、停下来 → 截停、记下来 → 落档、改了一堆不该改的地方 → 范围失控、起的名字跟老代码对不上 → 术语撞车。

这个习惯来自训练数据。AI 学过太多产品文案、技术博客、增长/管理类写作，这类文字过去十几年造了一堆自造词当行业黑话——"赋能""闭环""抓手""沉淀""对齐""打法""中台"——用这些词显得专业有力。AI 以为"好文案的特征就是这种压缩词"，写普通文章时也自动往这方向靠。

问题是这些词没长在日常汉语里。真人不说"这事翻车了"（除非在网上聊天），说"这事儿办砸了"。读者读到压缩词会在脑子里顿一下——"翻车 = 出问题"先解码一次再继续读。字数是省了，顺畅丢了。

自检：把你写的文字里每个双字或四字名词/动词圈出来，问"这个词是我从日常聊天里听来的，还是为了显得简练自己压出来的？"后者改回大白话，哪怕多出几个字。

承认困难，不假装简单

遇到真正难的地方，直接说"这里有点绕，我慢慢来"。读者读到这句话会放松——因为 TA 本来就觉得绕，现在确认了不是自己笨。

AI 默认会把难的地方一笔带过或用更抽象的词糊过去。糊过去的地方读者会卡住，但 TA 不会回来告诉作者，TA 只会放弃。

保留作者的声音

大师的文章都有明显的人格——Paul Graham 的冷静、费曼的调皮、Julia Evans 的真诚、Sagan 的敬畏。这不是风格装饰，是信任的来源。读者更愿意跟一个有人格的声音走，不愿意跟一份无名文档走。

AI 默认把人格磨平了——输出中性说明文体。这种文体最容易写，也最没读头。动笔前问自己：如果这段话是当面跟朋友讲，我会怎么讲？照那个讲法写下来。

教会读者，不要命令读者（写给 AI 也一样）

写给人的文章不会用 "你必须 X"、"绝对不要 Y" 这种口气——会显得居高临下。但 AI 写给 AI 读的指令文档（SKILL.md、流程文件、规则集）就特别爱用 MUST / NEVER / ALWAYS / 严禁 / 必须，以为这样更"硬"、更可靠。

其实反过来。命令式的规则只覆盖列出来的那几种情况，遇到没列到的边界情况，执行端只会两种反应：要么死板照搬规则结果做错事，要么完全失去判断依据瞎猜。教学式的说明把为什么这样做讲清楚，执行端遇到新情况能用原理自己推——"哦原来是为了避免 X，那这种情况下应该 Y"。

写给 AI 跟写给聪明学徒一个道理：你不会跟一个新来的工程师说"提交前必须运行 lint"，你会说"提交前跑一下 lint，不然 CI 会挂，回头还得再推一次很烦"。后者 TA 才知道遇到 lint 挂了该怎么权衡，遇到 CI 改了配置该怎么调整。

这个原则也适用于写 skill 的 description——别堆"触发词列表：'加功能'、'新接口'、'实现 X'……"。AI 调用 skill 时是看概念匹配的，给概念（"做新功能开发时触发"）比给死字符串列表覆盖面更广，遇到用户用了没列到的说法也能命中。

自检：写的指令里凡是出现 MUST / NEVER / ALWAYS / 严禁 / 必须，停一下问"我有没有讲为什么？"没讲就补上原因，让读者（人或 AI）能在边界情况里自己判断。规则越硬，执行端越呆。

沿着阅读时间线推演读者状态

写每一段时都在模拟读者读完上一段后脑子里的状态：TA 现在懂了什么、还不懂什么、下一秒最想问什么、有没有动力继续。下一段恰好对接 TA 当下的状态。

读这种文章的体验是"欸我刚想问这个，下一段就回答了"。这不是玄学，是作者在动笔时一段一段预判过。

判断手段：每段写完停下来问自己"TA 现在脑子里冒出的第一个问题是什么？"下一段就写那个问题的答案。如果回答不了，要么上一段没埋好（钩子没价值），要么顺序错了（读者还没准备好接收下一段）。

不同节的语气跟着功能走

翻译者姿态不等于全文都用对话口吻。文章里不同节的功能不同，语气跟着变：

• 叙述节（开头拉读者进来、讲为什么、讲理念）——用对话感，让读者感觉有个作者在旁边
• 导航节 / 参考节（路由表、目录索引、外链列表、字段速查）——用陈述句。读者来到这里是扫一眼找自己要的那行，不是听讲
• 反例 / 避坑节——直接陈述现象和原因，不需要扮演对话

判断手段：如果某节读起来像在聊天但功能是让读者快速定位信息，就是过度对话化了。表头、小标题、引导句里的"你怎么样"换成中性陈述。

写完扫一眼

• 第一段是从读者已经在的地方开始，还是从话题的形式起点开始？后者就重写
• 术语有没有赚权利？没讲过的挑出来用大白话讲一次，或者换掉
• 类比是从日常生活取的，还是从另一个技术概念平移？后者换掉
• 有没有假装简单的地方？卡住读者的点直接说"这里有点绕"
• 文章有没有作者的声音？全是中性说明文体就没了
• 每段第一句连起来读，是不是一条读者会自然走过去的认知路径？跳跃就重排
• 参考/导航节被写成对话句了吗？换成中性陈述
• 有没有 MUST / NEVER / ALWAYS / 严禁 这种硬命令？讲了为什么吗？没讲就补原因，让读者能自己判断边界
• 有没有自己压出来的复合词（翻车、收口、落档、范围失控这类）？换回大白话
• 删掉任意一句话，读者还能不能顺着认知路径走完？能就该删