本文为原文前 6,000 字符的节选翻译，完整内容请查看原文。

Anti-Patterns in Software Blogging

在软件开发中，我们收集反模式（anti-patterns）是为了识别那些导致软件效果不佳的常见特征。我认为将同样的方法应用于软件博客写作也会很有帮助，因此我整理了初学者博主最常犯的错误：漫无目的的引言、序言也算作漫无目的、“读者知道我所知道的一切，除了这一件事”、过度依赖链接、续集注入漏洞、过度正式、渲染 HTML 的基础知识出错、移动端页面溢出、难以阅读的字体、总结。

The meandering intro

漫无目的的引言

The most common mistake in software blogging, by far, is meandering. I constantly find myself several paragraphs into a post with no idea what the author is trying to tell me. Developers love specificity, so they start blog posts with backstory, historical context, and whatever else happens to be on their minds. That may be fun to write, but it’s not always interesting to read.

到目前为止，软件博客中最常见的错误就是漫无目的。我经常发现自己读了几段文章后，却完全不知道作者想表达什么。开发者喜欢具体细节，所以他们往往以背景故事、历史背景以及脑海中想到的任何其他内容作为博客的开头。这写起来可能很有趣，但读起来却未必吸引人。

From the reader’s perspective, there are a billion other articles they could be reading. Why should they read yours? They’re not going to invest 20 minutes to read it in full unless they expect a payoff. Give the reader a reason to continue reading. When a developer begins reading a blog post, they’re trying to answer two questions as quickly as possible: Did the author write this for someone like me? How will I benefit from reading it?

从读者的角度来看，还有十亿篇文章等着他们去读。为什么要读你的？除非他们预期能有所收获，否则他们不会投入 20 分钟去读完它。给读者一个继续阅读的理由。当开发者开始阅读一篇博客文章时，他们试图尽快回答两个问题：作者是为像我这样的人写的吗？阅读它对我有什么好处？

Give yourself the title and the first three sentences to answer both questions. The benefit you offer can be teaching the reader a new skill, explaining a concept, illustrating a new perspective, or delivering an entertaining rant. You just have to offer the reader something. They’re not going to read your blog post just because it’s there.

给自己留出标题和前三句话的时间来回答这两个问题。你提供的价值可以是教授读者一项新技能、解释一个概念、阐述一个新视角，或者发表一段有趣的吐槽。你必须为读者提供点什么。他们不会仅仅因为你的文章存在就去阅读它。

Preamble still counts as meandering

序言也算作漫无目的

Some bloggers write a compelling intro but clutter the reader’s path with extras like a subtitle, a bio, an image, or a famous quote. You can include any of these things, but recognize that they count against your “inspire the reader to keep reading” budget. Everything you put in the reader’s path is extra work that chips away at their finite supply of focus.

有些博主写了引人入胜的开头，却在读者的阅读路径上堆砌了副标题、个人简介、图片或名言等额外内容。你可以包含这些内容，但要意识到它们会消耗你“激励读者继续阅读”的预算。你放在读者路径上的每一件事都是额外的工作，会削弱他们有限的注意力。

“The reader knows everything I know except this one thing”

“读者知道我所知道的一切，除了这一件事”

Effective teachers compare new concepts to something the reader finds familiar. For example, if you were explaining Jellyfin, you might say, “Jellyfin is a streaming service like Netflix, except it’s open-source and private, so nobody monitors your viewing habits.” The tricky part is knowing what the reader finds familiar.

优秀的教师会将新概念与读者熟悉的事物进行比较。例如，如果你要解释 Jellyfin，你可能会说：“Jellyfin 就像 Netflix 一样的流媒体服务，只不过它是开源且私密的，所以没有人会监控你的观看习惯。”棘手的部分在于了解读者熟悉什么。

Lots of developers want to use Docker but don’t recognize terms like cgroups, jails, or *BSD. They might not even know what Linux is, especially if they’re seeking out an introduction to Docker. Instead of assuming the reader has your exact body of knowledge, minimize your assumptions about the reader.

许多开发者想使用 Docker，但并不认识 cgroups、jails 或 *BSD 等术语。他们甚至可能不知道 Linux 是什么，尤其是当他们正在寻找 Docker 入门介绍时。与其假设读者拥有和你完全一样的知识储备，不如尽量减少对读者的预设。

Overreliance on links

过度依赖链接

When’s the last time you read a book that directed you to stop reading, go buy a different book, read it in full, then continue your original book? Software bloggers do this all the time, though it’s more subtle. Bloggers often want to mention a term the reader might not know, but they don’t feel like explaining it themselves. Instead, they slap a link on the term and think, “Problem solved!”

你上次读一本书时，书里让你停止阅读、去买另一本书、读完后再回来继续读原书是什么时候？软件博主经常这样做，尽管方式更隐蔽。博主经常想提到一个读者可能不知道的术语，但又不想自己解释。于是，他们在术语上加个链接，心想：“问题解决了！”

The problem is not solved because the reader doesn’t want to interrupt their flow and go read a whole different site just to understand one word. Instead of relying on a link to do your work for you, give the reader the minimum possible explanation to understand your article. By all means, link to useful resources.

问题并没有解决，因为读者不想为了理解一个词而中断阅读流程，去访问一个完全不同的网站。与其依赖链接来替你完成工作，不如给读者提供理解文章所需的最低限度的解释。当然，链接到有用的资源是完全没问题的。