Anti-Patterns in Software Blogging
Avoiding Common Pitfalls: Anti-Patterns in Software Blogging
Originally authored by Michael Lynch, October 7, 2026
In the realm of software engineering, we utilize anti-patterns to identify recurring mistakes that lead to suboptimal code or system architecture. I believe this framework is equally applicable to the art of technical writing. To help aspiring authors, I have compiled a catalog of the most frequent errors encountered in software blogging.
The Catalog of Blogging Anti-Patterns
Below is a summary of the "code smells" found in many technical posts:
- The Meandering Introduction (The most prevalent offense)
- The Preamble Trap Remember: a preamble is still meandering!
- The Knowledge Gap (Assuming the reader is your clone)
- Link Dependency (Overreliance on external URLs)
- The Sequel Injection Bug (Cut off in original text)
- Excessive Formality
- Rendering Failures (Fumbling basic HTML)
- Mobile Layout Overflow
- Illegible Typography
1. The Meandering Introduction 🔗
By far, the most common mistake is the "slow burn." I often find myself deep into a post without a clear understanding of the author's objective.
Developers crave specificity. However, writers often indulge in long-winded backstories or historical tangents. While this is satisfying to write, it is often tedious to read. Readers have a finite amount of time and a million other tabs open; they won't commit to a 20-minute read without a guaranteed payoff.
The Reader's Mental Flow
When a developer lands on your page, they are running a mental script:
The Goal: Use your title and the first three sentences to answer both questions. Whether you are teaching a skill, explaining a concept, or venting in a professional rant, the value must be immediate.
Example of a "Good" Start: Title: A Simple Way to Write Better Go Tests "There's an excellent Go testing pattern that too few people know."
2. Preamble Still Counts as Meandering 🔗
Some writers craft a great intro but then bury it under a mountain of "fluff"—bios, subtitles, decorative images, or profound quotes.
Every element you place between the reader and the core content consumes their Attention Budget.
Force the reader to wade through a sea of preamble. Instead, keep the path to the value clear.
3. The "Reader Knows Everything I Know" Fallacy 🔗
Great educators bridge the gap between the unknown and the familiar.
Example: To explain Jellyfin, you might say: "Jellyfin is like Netflix, but it's private and open-source, meaning no one tracks your data."
The Anti-Pattern: Assuming the reader shares your exact technical history.
| Approach | Example | Why it Fails/Succeeds |
|---|---|---|
| Bad | "I'll introduce Docker to people who've never heard of it." (Then proceeds to discuss cgroups and *BSD). | Assumes the reader knows Linux internals. |
| Good | "Docker packages your app so it runs consistently in any environment using human-readable text files." | Defines the tool by its utility, not its internals. |
How to Audit Your Assumptions
To avoid this, try this workflow:
- List every technical term used in the post.
- Categorize them into "Common Knowledge" vs. "Niche Knowledge."
- Read the draft from the perspective of a novice.
- Replace or define any term that feels like a barrier.
As Tyler Cipriani noted during the editing of The future of large files in Git is Git, explicitly listing what the audience knows is a "mind-blowing" exercise in clarity.
4. Overreliance on Links 🔗
Imagine reading a novel that tells you to stop, go buy another book, read it entirely, and then return to the original story. You'd be annoyed. Yet, software bloggers do this constantly by linking to a term they are too lazy to explain.
The Problem: Readers do not want to break their flow to navigate a 20,000-word manual just to understand one sentence.
Comparison of Link Usage:
❌ The Bad Way
Assign firewall rules to prevent external traffic from reaching your database.
(Link points to the massive FreeBSD manual) This dumps a huge workload on the reader.
✅ The Good Way
A firewall is a system that restricts how hosts and networks communicate with an app. You can increase security by configuring firewall rules to only allow inbound requests to your database server when they originate from your app server.
(Link provided as a bonus resource) The reader gets the gist without leaving the page.
The Golden Rule:
Your target reader should be able to comprehend your entire article from start to finish without clicking a single external link.
5. The Sequel Injection Bug 🔗
These days, ev...