Anti-Patterns in Software Blogging

The most frequent mistake in software blogging, by far, is meandering. Developers love to start blog posts with backstory, historical context, and whatever else happens to be on their minds. This may be enjoyable to write, but it's not always engaging for readers. In today's fast-paced world, readers have a multitude of articles to choose from.

They won't invest 20 minutes reading your post unless they believe you'll provide a payoff. The introduction of a blog post should answer the reader's two primary questions quickly: What value will this article provide? Why should I read it? A compelling introduction should clearly convey the article's relevance to programmers using the relevant programming language and outline the benefit of learning a new technique quickly.

While it's acceptable to include additional elements like a subtitle, bio, image, or famous quote, these elements consume the reader's limited attention and should be used sparingly. Effective teachers often compare new concepts to familiar ideas to help readers grasp the material. For example, when 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."

When introducing Docker to developers who have never heard of it, the author compares it to a simplified front-end for Linux cgroups or jails in *BSD. Developers may not recognize Docker terms like cgroups, jails, or *BSD, or even understand what Linux is. To avoid assuming the reader's background knowledge, minimize assumptions about the reader's background.

Instead, provide a clear definition of Docker as a tool for creating consistent, reproducible environments for applications. Write your blog post with the target reader in mind, considering what they already know. List the terms they recognize and those they don't. Re-read your article, replacing technical terms with more accessible explanations if necessary.

Effective bloggers assume the reader is likely unaware of certain terms and provide explanations as needed. By minimizing assumptions and providing clear explanations, bloggers can create content that resonates with a wider audience.