软件博客写作中的反模式

# 软件博客写作的反模式 来源：https://refactoringenglish.com/blog/anti-patterns-software-blogging/ 在软件开发中，我们收集反模式，以便识别那些导致软件质量不佳的常见模式。我觉得软件博客写作也值得做同样的事情，于是我整理了初学博主最常犯的错误。 - [漫无边际的开场](https://refactoringenglish.com/blog/anti-patterns-software-blogging/#the-meandering-intro) - [前言铺垫也算漫无边际](https://refactoringenglish.com/blog/anti-patterns-software-blogging/#preamble-still-counts-as-meandering) - ["读者除了这一点，其他的都跟我一样懂"](https://refactoringenglish.com/blog/anti-patterns-software-blogging/#the-reader-knows-everything-i-know-except-this-one-thing) - [过度依赖链接](https://refactoringenglish.com/blog/anti-patterns-software-blogging/#overreliance-on-links) - [续集注入漏洞](https://refactoringenglish.com/blog/anti-patterns-software-blogging/#the-sequel-injection-bug) - [过度正式](https://refactoringenglish.com/blog/anti-patterns-software-blogging/#excessive-formality) - [搞不定 HTML 渲染基础](https://refactoringenglish.com/blog/anti-patterns-software-blogging/#fumbling-on-the-basics-of-rendering-html) - [移动端页面溢出](https://refactoringenglish.com/blog/anti-patterns-software-blogging/#page-overflow-on-mobile) - [难以阅读的字体](https://refactoringenglish.com/blog/anti-patterns-software-blogging/#unreadable-font) - [总结](https://refactoringenglish.com/blog/anti-patterns-software-blogging/#summary) ## 漫无边际的开场🔗 ([https://refactoringenglish.com/blog/anti-patterns-software-blogging/#the-meandering-intro](https://refactoringenglish.com/blog/anti-patterns-software-blogging/#the-meandering-intro)) 软件博客写作中最常见的错误，毫无疑问就是漫无边际。我经常读了好几段之后，还完全不知道作者到底想说什么。 [](https://refactoringenglish.com/blog/anti-patterns-software-blogging/not-quite-how-devs-read-top-panels-stacked.webp) 开发者喜欢具体的内容，所以他们常常在博客开头写背景故事、历史背景以及脑子里想到的其他一切。这样写也许挺有趣的，但读起来未必有意思。 从读者的角度来看，还有上亿篇文章等着他们去读。他们为什么要读你这篇？如果没有预期的收获，他们是不会花 20 分钟从头读到尾的。给读者一个继续读下去的理由。 当开发者开始读一篇博客文章时，他们想尽快回答两个问题： 1. 这篇文章是为我这样的人写的吗？ 2. 读了它我能得到什么？ 给自己限定——标题加上前三句话，必须回答这两个问题。 你能提供的收获可以是：教读者一项新技能、解释一个概念、展示一个新视角，或者来一段有趣的吐槽。你只需要给读者*点什么*。他们不会仅仅因为文章存在就去读。 这是我最近写的一篇文章（https://mtlynch.io/if-got-want-improve-go-tests/），开门见山： **`if got, want`：写出更好 Go 测试的简单方法** 有一个非常棒的 Go 测试模式，但知道的人太少了。我可以在 30 秒内教你。 这段开场白简洁地传达了两件事：这篇文章与使用 Go 编程语言的程序员相关；其价值在于教他们一项可以快速学会的新技术。 ### 前言铺垫也算漫无边际🔗 ([https://refactoringenglish.com/blog/anti-patterns-software-blogging/#preamble-still-counts-as-meandering](https://refactoringenglish.com/blog/anti-patterns-software-blogging/#preamble-still-counts-as-meandering)) 有些博主的开头写得不错，但在读者的阅读路径上堆满了副标题、个人简介、配图或名人名言之类的多余内容。这些东西都可以放，但要认识到它们会消耗你"激励读者继续阅读"的预算。你放在读者阅读路径上的每一样东西，都是额外的工作，会一点点蚕食他们有限的注意力。 [](https://refactoringenglish.com/blog/anti-patterns-software-blogging/too-much-preamble.webp) ## "读者除了这一点，其他的都跟我一样懂"🔗 ([https://refactoringenglish.com/blog/anti-patterns-software-blogging/#the-reader-knows-everything-i-know-except-this-one-thing](https://refactoringenglish.com/blog/anti-patterns-software-blogging/#the-reader-knows-everything-i-know-except-this-one-thing)) 优秀的教师会把新概念与读者熟悉的事物做类比。比如，如果你要介绍 [Jellyfin](https://jellyfin.org/)，你可以说："Jellyfin 是一个类似 Netflix 的流媒体服务，但它是开源且私密的，没有人会监控你的观看习惯。"难就难在，怎么知道读者熟悉什么。 > 在本文中，我将向从未听说过 Docker 的开发者介绍 Docker。 > > Docker 很简单。它不过是 Linux cgroups 的一个前端界面。你知道 \*BSD 的 jail 吗？Docker 就是它的 Linux 版本。 很多开发者想用 Docker，但看不懂 cgroups、jail 或 \*BSD 这些术语。他们甚至可能不知道 Linux 是什么，尤其是在他们专门来找 Docker 入门教程的时候。 [](https://refactoringenglish.com/blog/anti-patterns-software-blogging/readers-brain.webp) 与其假设读者拥有和你完全一样的知识体系，不如尽量减少对读者的假设： > Docker 是一个用于打包应用的工具，无论应用运行在哪里，都能保持一致且可复现的运行环境。Docker 允许你用人类可读的文本文件来定义应用的环境和依赖。这些文件记录了应用的运行需求，即使经过不同团队多年的修改，你也能确切知道它是如何工作的。 写博客时，想想你的目标读者。他们懂什么？想象一个你在现实中认识的朋友或同事。列一份清单：哪些术语他们认识，哪些不认识。然后重新阅读你的博客文章，每当遇到一个技术术语，就想想你的参照读者能否理解。 > 你描述的正是我心目中的读者，但我从来没尝试过把他们懂的东西列出来。把我草稿中的假设和你的清单对比了一下，太震撼了。——Tyler Cipriani，在我编辑"The future of large files in Git is Git"（https://tylercipriani.com/blog/2025/08/15/git-lfs/）一文时对他目标读者的假设提出质疑后的感想。 ## 过度依赖链接🔗 ([https://refactoringenglish.com/blog/anti-patterns-software-blogging/#overreliance-on-links](https://refactoringenglish.com/blog/anti-patterns-software-blogging/#overreliance-on-links)) 你上次读到一本书，让你停下来、去买另一本书、把它读完、再回来接着读，是什么时候？软件博主经常做这种事，只是方式更隐蔽一些。 博主经常想提到一个读者可能不懂的术语，但自己又懒得解释。于是就在术语上贴一个链接，心想："问题解决了！" 问题并没有解决，因为读者不想打断自己的阅读节奏，仅仅为了理解一个词就跑去读一个完全不同的网站。 > 为[防火墙](https://docs.freebsd.org/en/books/handbook/firewalls/)配置规则，阻止外部流量访问你的数据库。 上面链接的 FreeBSD 手册是一份优秀的资源，但防火墙那一章大约有两万字。当你链接到这样一个冗长的页面时，你把一大堆工作甩给了读者。 与其指望链接替你完成解释工作，不如给读者提供理解你的文章所需的最少限度的解释。 > [防火墙](https://docs.freebsd.org/en/books/handbook/firewalls/)是一种限制主机和网络如何与应用通信的系统。你可以通过配置防火墙规则来提高 Web 应用的安全性——只允许来自应用服务器的入站请求访问你的数据库服务器。 当然，链接有用的资源没问题，但要让它们成为加分项而非前置条件。把读者留在页面上。你的目标读者应该能够从头到尾愉快地理解你的文章，而不需要点击任何链接。 ## 续集注入漏洞🔗 ([https://refactoringenglish.com/blog/anti-patterns-software-blogging/#the-sequel-injection-bug](https://refactoringenglish.com/blog/anti-patterns-software-blogging/#the-sequel-injection-bug)) 如今，一切要么是续集要么是重启，博客文章也不例外。我见过很多博客文章是这样开头的： > 在第一部分中，我们学习了五重链表，以及它如何将你每日的代码行数产出提升 100 倍。在今天的博客中，我将展示 `goto` 语句如何让你 scrunkmax（一个我在第一部分中发明的术语——还记得吗？）。 很遗憾地告诉你，大多数读者并没有读过第一部分。如果你以为上一篇文章在读者脑海中还记忆犹新，他们只会想："哦，现在连*开始*读都得多做一道功课？" 提到之前的文章没问题，但别一上来就这么干。当你链接到往期文章时，总结一下相关内容，而不是强迫读者回去通读全文。 如果你写的是你从零开始搭建的业余操作系统，那确实可能需要多篇博客文章，但绝大多数"续集"文章只需要多花 3% 的精力就能成为独立成篇的文章。 ## 过度正式🔗 ([https://refactoringenglish.com/blog/anti-patterns-software-blogging/#excessive-formality](https://refactoringenglish.com/blog/anti-patterns-software-blogging/#excessive-formality)) 初学软件博客的人患有一种集体幻觉，以为必须用生硬、过度正式的方式写作，人们才会认真对待你： > 在本项目的整个生命周期中，我和我的队友们利用了若干静态分析工具。 你不是在给 1988 年 IBM 的 80 岁高管写东西。你的领域是软件开发，这是最不摆架子的白领工作之一。读你文章的人可能穿着睡衣和人字拖，一边吃着键盘旁边的麦片。他们不期望、也不想要你用法律文件的腔调说话。 就用你平时说话的方式来写。 > 在这个项目中我们试了几款静态分析工具。 随着越来越多的开发者把写作外包给 AI，软件博客正变得平淡乏味、千篇一律。读者渴望看到有个性的文字。以下是 Joel Spolsky 的一个随机句子，他是[有史以来最优秀的软件博客作者](https://refactoringenglish.com/blog/software-essays-that-shaped-me/#-by-joel-spolsky-2000)： > 那些在高中时用 BASIC 为 Apple II 写 Pong 游戏的优等生们，上了大学之后，学了计算机科学 101、学了数据结构课，而当他们碰到指针那一块的时候，大脑就彻底爆炸了，然后你还没回过神来，他们就已经改专业去学政治学了，因为上法学院看起来是个更好的选择。——Joel Spolsky，"The Perils of JavaSchools"（https://www.joelonsoftware.com/2005/12/29/the-perils-of-javaschools-2/） 这不是 Spolsky 最精彩的一句话，但很能体现他的风格。随意、亲切、不装腔作势。听起来就像他在午饭时给朋友们讲故事。你可以在 [Kathy Sierra](https://web.archive.org/web/20070503012853/http://headrush.typepad.com/)、[Terence Eden](https://shkspr.mobi/blog/) 和 [Raymond Chen](https://devblogs.microsoft.com/oldnewthing/) 的文章中看到同样的风格。他们不是在试图显得聪明——他们只是想做自己，而这正是读者喜欢的。 ## 搞不定 HTML 渲染基础🔗 ([https://refactoringenglish.com/blog/anti-patterns-software-blogging/#fumbling-on-the-basics-of-rendering-html](https://refactoringenglish.com/blog/anti-patterns-software-blogging/#fumbling-on-the-basics-of-rendering-html)) 软件博客写作中最难的部分是写出引人入胜的文章，所以看到那么多软件博主把本应简单的部分——制作一个基本的网页——搞砸了，实在让人感到沮丧。 ### 移动端页面溢出🔗 ([https://refactoringenglish.com/blog/anti-patterns-software-blogging/#page-overflow-on-mobile](https://refactoringenglish.com/blog/anti-patterns-software-blogging/#page-overflow-on-mobile)) 对移动端读者来说，最糟糕的错误就是让页面溢出屏幕，迫使读者来回滚动才能读完你的文章。通常原因是你有一张图片或一段代码片段坚持使用桌面端尺寸，把页面其余部分的布局搞乱了。 > 你的浏览器不支持 video 标签。 让文本在移动端溢出屏幕，会造成极其糟糕的阅读体验。 Firefox 和 Chrome 的桌面版都有移动端预览模式。发布之前，用移动端预览检查你的文章，排查常见的渲染问题。 不要低估你的移动端读者。根据我的统计数据，有 25% 的人正在手机上阅读这个页面。在我的[个人博客](https://mtlynch.io/)上，这个比例是 35%。 ### 难以阅读的字体🔗 ([https://refactoringenglish.com/blog/anti-patterns-software-blogging/#unreadable-font](https://refactoringenglish.com/blog/anti-patterns-software-blogging/#unreadable-font)) 选择易于阅读的字体颜色和字体。别再用浅灰背景上的深灰文字了。Firefox 和 Chrome 都有内置工具，会帮你标记出对比度过低的文字。 [](https://refactoringenglish.com/blog/anti-patterns-software-blogging/low-contrast.webp) Firefox 的无障碍工具正在识别低对比度文字 如果你不想费心寻找完美的字体，Braille Institute 有一款免费字体叫 [Atkinson Hyperlegible](https://www.brailleinstitute.org/freefont/)，阅读起来特别舒适，即使对视力不佳的读者也是如此。 ## 总结🔗 ([https://refactoringenglish.com/blog/anti-patterns-software-blogging/#summary](https://refactoringenglish.com/blog/anti-patterns-software-blogging/#summary)) - **给读者一个令人信服的继续阅读的理由。** 在标题和前三句话之内就把它说出来。 - 常见理由：他们想听一个有趣的故事、学一项有用的技巧，或理解一个与他们相关的概念。 - **质疑你对读者知识水平的假设。** 想想你期望读者认识哪些概念和术语，重新阅读文章，确保内容符合这些预期。 - **读者应该能够从头到尾读完你的文章，而不需要点击链接或悬停查看提示。** 链接应该让读者有机会更深入地探索主题，但它们应该是加分项而非前置条件。 - **避免把文章呈现为某篇前文的续篇。** 假设大多数读者没有读过你之前的文章。总结他们需要了解的相关内容，而不是期望读者去读你所有的往期文章。 - **去掉正式腔。** 用你在现实生活中说话的方式来写。 - **在浏览器的移动端视图中测试你的文章。** 确保文本不会溢出屏幕，不会迫使读者在阅读时左右滚动。 - **使用浏览器测试工具，找出让文章难以阅读的低对比度文字。** --- *"Not Quite How Developers Read" 和 "What Reader Knows" 插图由 [Piotr Letachowicz](https://cartoony.eu/) 绘制。*