软件技术博客写作的反模式
文章摘要
Michael Lynch 正在写一本面向程序员的写作书《Refactoring English》，这篇文章借用了软件开发里「反模式」的概念：既然我们会收集导致糟糕代码的常见做法，不如也把新手技术博主最常犯的错误整理出来。文中列出的反模式如下。
1. 绕来绕去的开头。 作者认为这是技术博客里最常见的问题。程序员喜欢交代细节，于是文章一上来就是背景、历史和各种随想，读了好几段仍不知道作者想说什么。读者手边有无数文章可读，没有预期的回报，不会投入 20 分钟读完你的文章。读者打开文章时想尽快弄清两件事：这篇是不是写给我这类人的？读了我能得到什么？作者建议用标题加前三句话回答这两个问题。他举了自己一篇 Go 测试文章的开头作为正面例子：开门见山地说「有一个很少人知道的 Go 测试模式，我 30 秒就能教会你」。
2. 铺垫也算绕。 有些作者开头写得不错，却在读者的必经之路上塞了副标题、个人简介、配图、名人名言。这些东西可以有，但都会消耗读者有限的注意力，占用「让读者继续读下去」的预算。
3.「读者什么都懂，只差这一点」。 好的讲解会把新概念和读者熟悉的东西类比，难点在于判断读者到底熟悉什么。反面例子是向从没听说过 Docker 的人解释「Docker 不过是 Linux cgroups 的漂亮前端，类似 BSD 的 jail」，而这类读者多半不知道 cgroups 和 jail 是什么。作者建议找一个现实中认识的人作为参照读者，列出他懂和不懂的术语，再站在他的角度重读全文。文中引用了 Tyler Cipriani 的反馈：这种方法让他意识到自己的草稿里藏着很多假设。
4. 过度依赖链接。 很多作者遇到读者可能不懂的术语，懒得解释，挂一个链接就算了。这相当于让读者先停下来去读另一本书。作者的例子是给「防火墙」挂上 FreeBSD 手册链接，而那一章有约两万字。正确做法是在正文里给出理解所需的最少解释，链接只作为延伸阅读，而不是前置作业。目标读者应该能不点任何链接就从头读到尾。
5.「续集注入」bug。 很多文章开头就说「在第一部分里我们学到了……」，但大多数读者没读过第一部分。可以引用以前的文章，但不要一开头就引用，并且要把相关内容概括出来。作者认为绝大多数续集文章只要多花约 3% 的功夫，就能写成独立的文章。
6. 过度正式。 新手常误以为必须写得一板一眼才会被认真对待，比如把「我们试了几个静态分析工具」写成冗长的被动句。作者调侃说，读者多半穿着睡衣、一边吃麦片一边看你的文章，不需要你像法律文件那样说话。他还指出，如今很多开发者把写作交给 AI，技术博客正变得千篇一律，读者渴望有个性的文字。他推崇 Joel Spolsky（称其为史上最好的软件博主），以及 Kathy Sierra、Terence Eden、Raymond Chen 那种随意、亲切、不装腔作势的风格。核心建议是：怎么说话就怎么写。
7. 连 HTML 都没做好。 写得引人入胜是最难的部分，网页本身却该是最容易的部分。一是移动端溢出：图片或代码块按桌面宽度渲染，导致读者要左右滚动。作者的统计显示，这篇文章 25% 的读者用手机阅读，他个人博客的比例是 35%，所以发布前应该用浏览器的移动预览检查。二是字体难读：别再用浅灰底配深灰字，可以用浏览器自带的对比度检查工具；如果不想挑字体，可以用盲文研究所免费的 Atkinson Hyperlegible。
文末总结了以上要点，并附上新书的折扣广告。
HN 评论精华
帖子获得 334 分、约 150 条评论。作者 mtlynch 在帖子里回复了不少评论。讨论主要围绕「讲故事」与「开门见山」的取舍，也有不少人认为这些规则太主观。
教学不是讲故事？ phreack 坚持认为教育不是讲故事，不应该把「反转」和「揭秘」留到最后；好的讲解应该先说要讲什么、再讲、最后总结。他还认为 LLM 让这个问题更严重了。DonaldPShimoda 引用本科导师的话：「论文和报告不是谋杀悬疑小说」，目的是让读者理解你的结论，而不是重演你的顿悟过程。mrweasel 推荐经典论文《A Rational Design Process: How and Why to Fake It》，主张在文档中把后来的发现放回「理性世界里本该出现的位置」；rswail 把它比作合并前的 squash 和 rebase。另一方的 godelski 认为人类天生喜欢故事，故事也是压缩信息的好方法，问题在于讲得好不好。mtlynch 本人也承认这里有矛盾：Paul Graham 和 Joel Spolsky 的很多文章并不开门见山，却依然出色。pchristensen 和 FlyingSnake 认为，那是因为他们成名于注意力还没那么稀缺的时代。wavemode 则指出，两人写的是观点文章，不是教学内容。
「先成为专家再写」？ mcphage 最讨厌「做过一次就以专家口吻教别人」的文章。dewey 担心这会变成给写博客设门槛。mtlynch 回应说，以新手身份写作很有价值，前提是坦白自己是新手，并举 Julia Evans 的「Some notes on using nix」为例。jrochkind1 建议分享心得时写清楚自己不确定的地方，并提出开放问题。
「每句话的唯一目的是让人读下一句」。 joshkel 引用 Joseph Sugarman 的这条写作建议。feoren 尖锐反对，认为这是在制造空洞的、TikTok 式的流量诱饵，「为了对抗 AI 垃圾，你自己变成了 AI 垃圾」。layer8 也认为，如果第一句的唯一目的是引出第二句，那它可以删掉。joshkel 随后承认自己引用得不够审慎。
风格是主观的。 layer8 说他不喜欢太口语化的技术文章，作者又不是他的朋友，他更喜欢 Dijkstra 那种中性、就事论事的文风。mtlynch 回应说，博客的好处就是口味多样，总有人更喜欢你的写法。kkapelon 偏爱「像栈一样」读文章：读 A 时跳去读 B，读完再回来，他觉得这说明作者承认别人讲得更好。dspillett 提醒不要矫枉过正，正文给出概要的同时仍应附上链接。chris_money202、ragall、zrail、abeyer 都认为这些建议取决于目标读者，比如面向研究者时引用就很重要。0x20cowboy 说博客是个人日记，「不是所有东西都是产品」，layer8 反驳说这等于说世上没有糟糕的写作。adityaathalye 自嘲他的博客集齐了所有反模式，因为是写给自己的；mtlynch 追问既然如此为何还要投稿 HN，两人进行了一段友好的交流。
AI 与博客的未来。 多人提到 AI 生成的博客越来越多：jrochkind1 觉得每周看到的软件博客多数像是 LLM 写的，通常很糟，篇幅是理想长度的三倍。linsomniac 说技术博客也快需要美食博客那种「跳到菜谱」按钮了。hashtag-til 问 2026 年开博客还有没有意义，jjfoooo4、zrail 回答说，写作的价值很大一部分归于作者自己的思考；SenHeng 说自己最近看到个人博客反而会先点开原文、再看评论；ogou 则说自己 2015—2025 年坚持写长篇技术博客，如今流量蒸发，99% 是爬虫，已经停更。kdazzle 调侃说，他晚上喝两杯后写冗长的叙事，就是为了让 OpenAI 多花点钱去爬。
补充的反模式。 mexicocitinluez、0cf8612b2e1e 提出「不写发布日期」；vhantz 认为把总结放在结尾也是反模式；danieltanfh95 吐槽这篇文章自己就不好读，最重要的总结列表应该放在最前面。