刚啃完那篇《How the Heck Does GPS Work?》，作者用“卫星扔纸条算位置”讲清原理，我直接拍大腿——这才是技术传播该有的样子！反观某些开源项目文档，堆满“赋能”“闭环”“范式”，新手看得想摔键盘。Rails当年为啥火？人家连migration命令都配了“就像给数据库做拉链手术”这种梗。开源不是写论文，文档带点烟火气反而更持久。维护者兄弟们，写文档前默念三遍：我妈能看懂吗？（别问，问就是我妈用高德导航十年仍分不清经纬度 (￣▽￣*)ゞ）

前些年帮一个老项目补文档，写到“异步非阻塞I/O”时卡了三天。最后干脆画了幅图：一个茶馆跑堂同时给十桌客人续水，谁杯子空了就搭把手——老爷子看了直点头。技术这东西，说穿了不过人情世故的变体。你提到GPS那篇，让我想起九十年代在Usenet上读过一篇讲TCP/IP的，作者拿寄信丢信封打比方，至今还记得。其实哪有什么高深，不过是怕别人真看懂了？文档写得云山雾罩，有时是心虚，有时是懒。Rails那句“拉链手术”妙就妙在带体温——代码冷冰冰，话得热乎着说。你妈分不清经纬度没关系，只要她知道点“开始导航”就能到家，这不就是技术该干的事儿么……话说回来，你最近在啃哪个项目的文档？

wise_x提到茶馆跑堂那幅图，倒让我想起早年在成都帮人看一个通信中间件的文档。那会儿有个老师傅非说“消息队列”得比作赶集——货郎担子不等人，买家没接住就扔地上，下一担又来了。仔细想想我一开始嫌土，后来发现连他孙女都能照着配通了测试环境。说到底，比喻不在雅俗，而在是否贴着对方的日子走。你Usenet那篇TCP/IP的信封故事，怕也是因为写的人心里装着收信人，不是只顾显摆邮戳多稀有。对了，你补文档时有没有试过让完全不懂技术的人先念一遍草稿？坦白讲我后来养成这习惯，改掉不少自以为是的“显然”。最近真在啃啥文档？

sage_2001提到“让完全不懂技术的人先念一遍草稿”，这个做法我试过，但结果有点意外。去年帮一个朋友审他写的Rust异步运行时文档初稿，特意拉我妈来读——她退休前是小学语文老师，认字没问题，逻辑也清晰。结果她卡在“Future不是值，而是一个承诺”这句上，反问：“那它到底有没有？” 我们当时笑成一团，但回头一想，问题出在“承诺”这个词本身带道德色彩，容易引发语义联想。后来换成“Future像外卖订单：下单了不代表饭到手，但你知道它在路上”，她秒懂。

这让我意识到，比喻不仅要“贴日子”，还得避开认知陷阱。茶馆跑堂、赶集货郎之所以有效，是因为动作链条完整（空杯→续水、接不住→丢地上），而“承诺”“范式”这类词本质是抽象封装，反而制造了新的黑箱。其实RFC 3117里早就提过：protocol documentation should avoid metaphors that imply agency where none exists（别给无意识系统强加意图）。可惜现在连API文档都爱写“智能推荐”“自动感知”，搞得用户以为代码真有脑子。

说到Usenet那篇TCP/IP信封文，我查过存档，作者是Dave Taylor，1994年发在comp.protocols.tcp-ip。他原话其实是：“If your letter gets lost, the post office doesn’t care—but TCP will send a new one and nag you until you sign for it.” 关键在“nag”这个动词，把重传机制拟人成邮差拍门，比单纯说“可靠传输”生动十倍。可见好比喻得带点小情绪，不能只讲结构。

最近我在啃Apache Kafka的KRaft模式文档，官方用“controller quorum like a group chat deciding who’s admin”解释leader选举，老实说不如直接画状态机。可能有些概念硬要烟火气反而失真？btw你当年补文档时，有没有遇到过“比喻比原文更难懂”的情况？

说到让不懂技术的人念草稿那个习惯，我前几个月改这边一个露营导航工具的开源文档真这么干了。
我室友是学油画的，连terminal怎么开都不知道，凡是她皱眉头问“这啥”的地方我全改，改完之后好多新手说这是他们见过最舒服的文档。
那个货郎担子的比喻真的戳我，上次给国内我妹讲消息队列，憋了半天讲术语她全程懵，我顺嘴说这个例子，她当场就懂了，绝了。
话说有没有人碰到过改完通俗文档，被老维护吐槽“不够专业”的？我上次就碰到，说我写得太口水了，literally无语啊。