Anti-Patterns in Software Blogging软件博客写作中的反模式

In software development, we collect anti-patterns to recognize common traits that lead to poor outcomes in our software. I thought it would be helpful to do the same for software blogging, so I’ve catalogued the most frequent mistakes I see from beginner bloggers.在软件开发领域，我们会收集“反模式”来识别那些会导致不良结果的常见做法。我认为将这一概念应用到软件博客写作中也很有帮助，因此我整理了初学者在撰写技术博客时最常犯的一些错误。

• The meandering intro
  • Preamble still counts as meandering序言也属于漫无边际的铺垫
• “The reader knows everything I know except this one thing”“读者除了这一点外，知道我所知道的一切”
• Overreliance on links过度依赖链接
• The sequel injection bug续集注入缺陷
• Excessive formality过度正式
• Fumbling on the basics of rendering HTML
  • Page overflow on mobile移动端页面溢出
  • Unreadable font字体难以阅读
• Summary总结

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.从读者的角度来看，还有成千上万篇其他文章等着他们去读。他们为什么要读你的文章？除非他们预期能有所收获，否则不会投入20分钟去阅读全文。请给读者一个继续阅读的理由。

When a developer begins reading an blog post, they’re trying to answer two questions as quickly as possible:当开发者开始阅读一篇博客文章时，他们试图尽快回答两个问题：

1. Did the author write this for someone like me?作者是为我这类人写的吗？
2. How will I benefit from reading it?阅读这篇文章对我有什么好处？

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.你提供的价值可以是教授读者一项新技能、解释一个概念、阐述一个新视角，或者仅仅是提供一段有趣的观点输出。你必须给读者提供某种东西。他们不会仅仅因为你的博客存在就去阅读它。

Here’s an article I wrote recently that gets straight to the point:以下是我最近写的一篇直奔主题的文章：

The introduction succinctly communicates that the article is relevant to programmers who use the Go programming language, and the value is teaching them a new technique they can learn quickly.这段引言简洁地传达了这篇文章与使用 Go 语言的程序员相关，其价值在于教授他们一种可以快速掌握的新技术。

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.许多开发者想使用 Docker，但并不了解 cgroups、jails 或 *BSD 等术语。他们甚至可能不知道什么是 Linux，尤其是当他们正在寻找 Docker 入门介绍时。

Instead of assuming the reader has your exact body of knowledge, minimize your assumptions about the reader:与其假设读者拥有和你完全相同的知识储备，不如尽量减少对读者的假设：

When you write a blog post, think about your target reader. What do they know? Imagine a friend or teammate you know in real life. Write a list of terms they would recognize and terms they would not. Then, re-read your blog post, and whenever you encounter a technical term, think about whether your reference reader would understand it.当你撰写博客时，思考一下你的目标读者。他们了解什么？想象一个你在现实生活中认识的朋友或队友。列出他们会识别的术语和不会识别的术语。然后，重读你的文章，每当你遇到一个技术术语时，思考一下你的参考读者是否能理解它。

You’re describing the audience I had in mind, but I’ve never tried listing out what that audience knows. Comparing your list against the assumptions in my draft is pretty mind-blowing.“你描述的是我心目中的目标受众，但我从未尝试过列出他们到底了解什么。将你的列表与我草稿中的假设进行对比，真是令人大开眼界。”

–Tyler Cipriani, when I challenged assumptions about his target reader while editing “The future of large files in Git is Git”——泰勒·西普里亚尼（Tyler Cipriani），当我在编辑《Git 中大文件的未来》一文时，对他关于目标读者的假设提出了质疑。

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.问题并没有解决，因为读者并不想打断思路去阅读一个完全不同的网站，仅仅是为了理解一个词。

The FreeBSD manual linked above is an excellent resource, but the chapter on firewalls chapter is about 20,000 words. When you link to such a wordy page, you dump a massive amount of work on the reader.上面链接的 FreeBSD 手册是非常优秀的资源，但关于防火墙的章节大约有 20,000 字。当你链接到如此冗长的页面时，你实际上是将巨大的阅读负担丢给了读者。

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, but make them a bonus rather than a prerequisite. Keep the reader on the page. Your target reader should be able to enjoy and understand your article from start to finish without clicking any links.当然，链接到有用的资源没问题，但要让它们成为锦上添花，而不是前提条件。让读者留在你的页面上。你的目标读者应该能够从头到尾享受并理解你的文章，而无需点击任何链接。

The sequel injection bug🔗续集注入缺陷🔗

These days, everything is either a sequel or a reboot, including blog posts. I see a lot of blog posts that open like this:如今，万物皆可续集或重启，包括博客文章。我看到很多博客文章是这样开头的：

In part one, we learned about quintuply linked lists and how they can 100x your daily LOC output. In today’s post, I’ll show you how goto statements let you scrunkmax (a term I invented in part one – remember?).在第一部分中，我们了解了五重链表以及它们如何让你的日常代码行数（LOC）输出提高 100 倍。在今天的文章中，我将向你展示 goto 语句如何让你实现 scrunkmax（这是我在第一部分中发明的一个术语——还记得吗？）。

I hate to break it to you, but most readers have not read part one. If you assume your last article is fresh in the reader’s mind, they’ll think, “Oh, now there’s extra work to even start reading?”很抱歉要打破你的幻想，但大多数读者并没有读过第一部分。如果你假设读者对上一篇文章记忆犹新，他们会想：“噢，现在连开始阅读都要做额外功课了？”

It’s fine to refer to your previous posts, but don’t do it right out of the gate. When you do link to past posts, summarize what was relevant rather than force the reader to go back and read it in full.引用之前的文章没问题，但不要一上来就这么做。当你链接到往期文章时，请总结相关内容，而不是强迫读者回去阅读全文。

If you’re writing about the hobby operating system you built from scratch, then sure, you probably need more than one blog post, but the vast majority of sequel posts could be standalone articles with like 3% more effort.如果你是在写自己从零构建的业余操作系统，那确实可能需要多篇博客，但绝大多数所谓的“续集”文章，只要多花 3% 的精力，完全可以写成独立的文章。

Excessive formality🔗过度正式🔗

Beginner software bloggers suffer from a mass delusion that you have to write in a stiff, overly formal way for people to take you seriously:初学者常有一种集体错觉，认为必须以生硬、过度正式的方式写作，别人才会认真对待你：

Several static analysis tools were utilized by my teammates and myself throughout the duration of this project’s lifetime.在本项目生命周期的全过程中，我和我的团队成员利用了多种静态分析工具。

You’re not writing for 80-year-old executives at IBM in 1988. Your field is software development, one of the least pretentious white-collar jobs out there. The person reading your article is probably wearing pajamas and flip flops while eating from a bowl of cereal next to their keyboard. They don’t expect or want you to talk like a legal document.你又不是在为 1988 年 IBM 的 80 岁高管们写报告。你从事的是软件开发，这是最不讲究排场的白领工作之一。阅读你文章的人可能正穿着睡衣和人字拖，在键盘旁吃着麦片。他们不希望也不需要你像写法律文件那样说话。

Just write the way you talk.像平时说话那样写就行了。

With so many developers delegating their writing to AI, software blogging is becoming bland and homogenous. Readers are hungry for writing with personality. Here’s a random sentence from Joel Spolsky, the best software blogger of all time:随着大量开发者将写作任务委托给 AI，软件博客正变得平淡且同质化。读者渴望看到带有个人风格的文字。这是史上最优秀的软件博主乔尔·斯波尔斯基（Joel Spolsky）的一句随笔：

All the kids who did great in high school writing pong games in BASIC for their Apple II would get to college, take CompSci 101, a data structures course, and when they hit the pointers business their brains would just totally explode, and the next thing you knew, they were majoring in Political Science because law school seemed like a better idea.所有那些在高中时用 BASIC 为 Apple II 编写乒乓游戏表现优异的孩子，进入大学后修读计算机科学 101 和数据结构课程，当他们接触到指针时，大脑会彻底炸裂。紧接着，你会发现他们转修了政治学，因为法学院看起来是个更好的主意。

– Joel Spolsky, “The Perils of JavaSchools”——乔尔·斯波尔斯基，《Java 学校的危险》

It’s not Spolsky’s best line, but it captures his style. It’s casual, personable, and unpretentious. It sounds like he’s telling a story to some friends at lunch. You can see the same style in the writing of Kathy Sierra, Terence Eden, and Raymond Chen. They’re not trying to sound smart–they’re just trying to sound like themselves, and that’s what readers enjoy.这虽然不是斯波尔斯基最精彩的一句话，但它捕捉到了他的风格。它随意、亲切且不装腔作势。听起来就像他在午餐时给朋友讲故事。你可以在凯西·塞拉（Kathy Sierra）、特伦斯·伊登（Terence Eden）和雷蒙德·陈（Raymond Chen）的文章中看到同样的风格。他们不是在刻意显摆聪明，而是在努力呈现真实的自己，这正是读者所喜爱的。

Fumbling on the basics of rendering HTML🔗在 HTML 渲染基础问题上笨手笨脚🔗

The hardest part of software blogging is writing in a compelling way, so it’s frustrating to see so many software bloggers bungle the part that should be easy: making a basic webpage.软件博客写作中最难的部分是写得引人入胜，因此看到那么多博主在最简单的事情上搞砸，真是令人沮丧：那就是制作一个基本的网页。

Page overflow on mobile🔗移动端页面溢出🔗

The worst mistake you can make for mobile readers is overflowing the screen so the reader has to scroll back and forth to read your article. Usually, it’s because you have an image or code snippet that insists on being desktop size and screws up the layout of the rest of the page.对于移动端读者来说，你所能犯的最严重的错误就是让页面溢出屏幕，导致读者必须左右滚动才能阅读你的文章。通常这是因为你放了一张图片或一段代码片段，它们非要以桌面端尺寸显示，从而破坏了页面其余部分的布局。

Desktop versions of Firefox and Chrome both have a mobile preview mode. Check your article with the mobile preview before you publish, and check for common rendering issues.桌面版的 Firefox 和 Chrome 都具备移动端预览模式。在发布文章前，请先用移动预览检查一下，并排查常见的渲染问题。

Don’t underestimate your mobile readers. According to my analytics, 25% of you are reading this page on your phones. On my personal blog, it’s 35%.不要低估你的移动端读者。根据我的分析数据，你们中有 25% 的人是在手机上阅读这篇文章的。在我的个人博客上，这个比例高达 35%。

Unreadable font🔗难以阅读的字体🔗

Choose a font color and family that are easy to read. Stop it with this dark gray text on a light gray background. Firefox and Chrome both have built-in tools that flag low-contrast text for you.选择易于阅读的字体颜色和字族。别再用浅灰色背景上的深灰色文字了。Firefox 和 Chrome 都内置了工具，可以为你标记出对比度过低的文字。

If you don’t feel like searching around for the perfect font, the Braille Institute has a free font called Atkinson Hyperlegible that’s particularly comfortable to read, even for readers with poor vision.如果你不想费心寻找完美的字体，布莱叶盲文研究所（Braille Institute）有一款名为 Atkinson Hyperlegible 的免费字体，阅读起来特别舒适，即使是视力较差的读者也能轻松阅读。

Summary🔗总结🔗

• Give the reader a compelling reason to continue reading. Get to it within the title and the first three sentences of your blog post.
  • Common reasons: they want to hear an entertaining story, learn a useful technique, or understand a concept that’s relevant to them.常见需求：读者想要听到有趣的故事、学习有用的技术，或者理解与他们相关的概念。
• Question your assumptions about what the reader knows and does not know.
  • Think about what concepts and terms you expect the reader to recognize and re-read your article to make sure it matches those expectations.思考一下你期望读者识别哪些概念和术语，并重读你的文章以确保其符合这些预期。
• The reader should be able to read your article from start to finish without clicking links or hovering for tooltips.
  • Links should allow the reader to explore topics more deeply, but they should be a bonus rather than a pre-requisite.链接应该让读者能够更深入地探索主题，但它们应当是锦上添花，而不是前提条件。
• Avoid presenting your article as a follow-up to a previous article.
  • Assume most readers haven’t read your previous articles. Summarize what’s relevant for them to know rather than expecting the reader to go read all your prior posts.假设大多数读者没有读过你的往期文章。总结对他们有用的相关内容，而不是指望读者去阅读你所有的过往文章。
• Drop the formality. Write the way you speak in real life.放下架子。像你在现实生活中说话那样写作。
• Test your articles in your browser’s mobile view.
  • Make sure that your text doesn’t overflow the screen and force the reader to scroll horizontally as they read.确保你的文字不会溢出屏幕，导致读者在阅读时被迫进行水平滚动。
• Use browser testing tools to find low-contrast text that makes your article difficult to read.使用浏览器的测试工具来发现那些导致文章难以阅读的低对比度文字。

“Not Quite How Developers Read” and “What the Reader Knows” illustrations by Piotr Letachowicz.《开发者阅读方式的不一致》和《读者知道什么》插图由 Piotr Letachowicz 绘制。