在软件开发中，人们会收集反模式（anti-patterns），以识别那些导致糟糕结果的常见特征。作者认为对软件博客也值得这样做，于是把自己从新手博客作者身上看到的最常见错误编录成一份清单。

软件开发中，我们收集反模式来识别导致糟糕结果的特征。我觉得对软件博客也这么做会有帮助，所以编录了新手博主最常犯的错误。

绕弯子的开头

软件博客中最常见的错误绝对是绕弯子。我经常读了几段还不知道作者想说什么。

开发者喜欢具体，写博客开头爱交代背景、历史脉络和脑子里冒出的其他东西。写起来可能爽，读起来未必有趣。

读者角度看，能读的文章海了去了。干嘛读你的？除非有回报，否则不会花20分钟通读。给读者一个继续读的理由。

开发者开始读时，会尽快弄清两件事：

1. 这文章是写给像我这样的人吗？
2. 读了有啥好处？

用标题和前三句话回答这两个问题。

好处可以是教新技能、解释概念、展示新视角或来段吐槽。总之得给点东西，人家不会因为你写了就去读。

这是我最近写的一篇直奔主题的文章：

if got, want：写好 Go 测试的简单方法

有个很棒的 Go 测试模式没几个人知道。我30秒就能教会你。

开头简明交代了文章面向 Go 程序员，价值是快速教会新技术。

前言也算绕弯子

有些博主开头吸引人，却用副标题、简介、图片或名人名言把路堵了。这些可以加，但要明白它们都在消耗“激励读者继续读”的额度。读者路上的每样东西都是额外负担，消磨他们有限的注意力。

“读者除了这一件事，其他都知道”

好老师会把新概念和读者熟悉的东西类比。比如解释 Jellyfin，可以说“像 Netflix 的流媒体服务，但开源私密，不监控观看习惯”。难点在于知道读者熟悉什么。

比如这篇想给没听过 Docker 的开发者做介绍，却写：“Docker 很简单，不过是 Linux cgroups 的漂亮前端。你懂 *BSD 的 jails 吗？Docker 就是那个的 Linux 版。”

很多想用 Docker 的人根本不认识 cgroups、jails 或 *BSD，甚至可能不知道 Linux 是啥。

别假设读者和你知识库一样，尽量减少预设：

Docker 是把应用打包成一致、可复现环境的工具。它让你用可读文本定义环境和依赖，记录需求，多年后也清楚怎么跑。

写时想好目标读者知道啥。想象现实中的朋友或同事，列张他们懂和不懂的术语表，然后重读文章，遇到术语就想想读者懂不懂。

你描述的是我心里想的读者，但我从没试过列清他们知道什么。把你的列表和我草稿里的假设对比，真让我大开眼界。

–Tyler Cipriani，我在编辑他的文章时挑战了他对目标读者的假设

过度依赖链接

你上次读一本书被要求停下去买另一本读完再回来，是什么时候？软件博主常干这种事，只是更隐蔽。

博主常提个读者可能不懂的词，自己懒得解释，丢个链接就觉得完事了。问题没解决，读者不想打断思路去别的站读一整页就为懂一个词。

例：分配 firewall 规则阻止外部流量访问数据库。FreeBSD 手册那章约两万字，链过去就是把海量工作甩给读者。

别靠链接偷懒，给读者能懂文义的最少解释：防火墙是限制主机网络与应用通信的系统。配规则只允许来自应用服务器的请求进数据库，就能提升安全。

尽可以链好资源，但当作添头而非门槛。留住读者。目标读者应能不点任何链接就从头读到尾。

续集注入 bug

如今啥都有续集重制，博客也是。很多开头像：

Part 1 学了五重链表如何百倍提升每日代码量。今天教用 goto 语句实现 scrunkmax（我 Part 1 发明的词，记得吗）。

不得不泼冷水，多数读者没读 Part 1。你以为上一篇文章读者记忆犹新，他们只会觉得“哦，刚开始读就有额外功课？”

可以提旧文，但别一开头就提。链旧文时要总结相关内容，别逼读者回去通读。

比如写从零造的爱好操作系统，确实要多篇。但绝大多数续集文只要多花 3% 精力就能独立成篇。

过度正式

新手博主有种集体错觉，觉得非得板着脸写才显得专业：

Several static analysis tools were utilized by my teammates and myself throughout the duration of this project’s lifetime.

你不是给1988年 IBM 80岁高管写。软件业最不装的白领工作之一。读你文章的很可能穿睡衣拖鞋、端着麦片碗。他们不想听你像法律文件。

就像平时说话那样写。

We tried a few static analyzers on this project.

越来越多人用 AI 写，博客变得 bland 同质。读者渴望有性格的文字。这是 Joel Spolsky 随机一句：

所有高中在 Apple II 上用 BASIC 写 pong 游戏的孩子，上大学修计算机101数据结构，一碰到指针大脑就炸了，接着去学政治，因为法学院似乎更好。

– Joel Spolsky, “The Perils of JavaSchools”

这不是他最好的一句，但抓住了风格：随意、有人情味、不装。像午饭时跟朋友讲故事。Kathy Sierra、Terence Eden、Raymond Chen 也是这风格。他们不装聪明，只做自己，读者就爱看。

在渲染 HTML 基础上栽跟头

软件博文最难是写得吸引人，可那么多人在本该简单的“做个基础网页”上翻车，真让人恼火。

移动端页面溢出

移动端最糟错误是屏幕溢出，读者得左右滚。通常是图片或代码块死守桌面尺寸搞乱布局。

移动端文字溢出体验极差。Firefox 和 Chrome 桌面版都有移动预览模式。发布前用移动预览检查常见渲染问题。

别小看移动读者。据分析，25% 的人用手机读这页。我个人博客是 35%。

难读的字号/字体

选好读的颜色和字体。别再深灰字配浅灰底了。Firefox 和 Chrome 有内置工具标出低对比度文字。

懒得找字体，Braille Institute 有免费字体 Atkinson Hyperlegible，连视力差的都舒服。

总结

• 给读者继续读的有力理由。在标题和前三句内搞定。常见理由：爱听有趣故事、学实用技巧或懂相关概念。
• 质疑你对读者知未知的假设。想清预期读者懂哪些概念术语，重读文章确保匹配。
• 读者应能不点链接、不悬停提示从头读到尾。链接供深入探索，是添头非门槛。
• 避免把文章写成前作续集。假设多数读者没读旧文，总结相关内容而非逼他们回去通读。
• 丢掉正式感。像平时说话那样写。
• 在浏览器移动视图测试文章。确保文字不溢出逼人横滑。
• 用浏览器测试工具找难读的低对比度文字。

社区普遍批评技术博客滥用故事化悬念与蜿蜒引言，主张直切重点并锚定读者已有认知；少数人则强调文风属主观，可接受延迟揭示或外链跳读。

技术写作不应套用故事结构，应当直白重复重点

• 不少人指出博主爱制造悬念、埋没导语，但技术内容需要开门见山；教育不是讲故事，应先声明结论再展开，甚至“剧透”和重复。（较多人） > 教育不是讲故事，结构应当反过来剧透和重复，像演示那样开头说将说啥、中间说、结尾总结。（@phreack）

最致命的是未将新主题对接读者熟悉概念

• 有读者认为相比拖沓引言，更严重的错误是文章不回答“这东西对比我已知什么、为何要关心”，导致门槛高；建议先讲没有该工具的痛点再比较。（少数人） > 最有害的错误是没把主题和读者熟悉的东西联系，应说明“相比熟悉的什么、为什么要在意”。（@ram1500natrluvr）

反感优化套路的平庸文章，看重作者个性

• 部分人宁愿读带个人痕迹的文字，而不是为触达率按固定模板产出的内容，认为后者可由任何人代笔。（少数人） > 我宁愿读略有个性迹象的，而不是又一篇套路化、任何人都写得来的营销优化文。（@rglullis）

写作偏好属主观，延迟揭示和外链亦可接受

• 个别读者表示不挑剔写法，有人享受不长文章的晚揭转折，或习惯像栈一样跳读外链文章，认为这反显作者知自身局限。（少数人） > 某些反模式是主观的，我读文如栈般跳链接不烦，还喜欢不长的文章晚揭示转折。（@kkapelon）

外链应自带总结，避免读者做家庭作业

• 有作者反思过度依赖链接不加总结，迫使读者做家庭作业；读者也呼吁技术博客加“跳到配方”直取核心，说明社区厌弃外链森林。（较多人） > 我以前太依赖链接，今后要总结链接内容，免得读者像做家庭作业。（@totallygeeky）

有价值的补充

• 写作时可依“首句只为让你读第二句”的递进法则保持连贯，缓解读者流失（源自约瑟夫·舒格曼的建议）。
• 大型语言模型加剧了废话泛滥，例如查询某技术概念时涌现大量永不及重点的长文。
• “跳到配方”式的直接跳转链接被呼吁引入技术博客，类比美食博客的改良。
• 需警惕“做一次就扮专家教别人”的撰文姿态，这是常见令人反感点。
• 社区其实渴望出现新一代类似 Stack Overflow 的实用知识源，侧面反映对当前博客不满。
• 许多人是好作家但坏编辑，社区需要更多个人故事只是第一段就应先给结论。