Software blogging anti-patterns
mtlynch’s field guide (refactoringenglish.com, captured verbatim → clippings/refactoringenglish-com-blog-anti-patterns-software-blogging.md) — editing patterns from someone who coaches software writers for a living. The through-line: the reader owes you nothing — “there are a billion other articles they could be reading,” so every element either earns the next paragraph or spends the reader’s finite focus.
The anti-patterns (with the fix)
- Meandering intros — backstory-first writing is fun to write, boring to read. The reader’s two questions, answerable in the title + first three sentences: did the author write this for someone like me? how will I benefit? Preambles (subtitle, bio, quote, image) count against the same budget.
- “The reader knows everything I know except this one thing” — assuming your knowledge baseline (Docker explained via cgroups and BSD jails to a reader who may not know Linux). Fix: pick a real person you know as the reference reader, list what they’d recognize, re-read the draft as them.
- Overreliance on links — “slap a link on the term, problem solved” just outsources the work; linking a 20,000-word FreeBSD chapter to explain one word dumps homework on the reader. Fix: give the minimum inline explanation; links are a bonus, never a prerequisite — “keep the reader on the page.”
- The sequel injection bug — opening with “in part one, we learned…” when most readers never read part one. Summarize what’s relevant; most sequels could be standalone “with like 3% more effort.”
- Excessive formality — “you’re not writing for 80-year-old executives at IBM in 1988”; the reader is in pajamas eating cereal. “Write the way you talk.” And the 2026 kicker: with developers delegating writing to AI, blogging is going “bland and homogenous” — readers are hungry for writing with personality (Spolsky, Kathy Sierra, Terence Eden, Raymond Chen as the canon: “not trying to sound smart — just trying to sound like themselves”).
- Bungled HTML rendering — mobile page overflow and other basics failing while the hard part (the writing) succeeds.
Why it matters now
- The anti-slop corollary: rule 5 is the writing-side of the Meat proxy / AI memes culture lane — AI text averages toward the formal-homogenous middle; personality is the differentiator that survives.
- Docs-as-product relevance: the “keep the reader on the page” rule is the human-side complement to Agent-accessible product — the same content discipline that makes docs agent-legible (self-contained, minimum inline explanation) makes them human-legible.
- Directly applicable to the Hugo blog lane and this vault’s evergreen-writing style: answer “for whom / what benefit” in the first three sentences, minimize assumed knowledge, links as bonus not prerequisite.
Vault kin
- Meat proxy (the slop-culture context) · Senior mindset (Fournier’s “design doc to resolution” — the writing-as-engineering-skill lane) · Agent-accessible product (docs convergence)