Michael Lynch has been editing software blogs long enough to see the same mistakes on repeat. This post is a pattern catalogue — seven named anti-patterns for developer writing, each with a before/after rewrite demonstrating the fix. The format is the argument: stop meandering, stop assuming your reader shares your exact knowledge graph, stop outsourcing explanation to hyperlinks. The strongest section is the curse-of-knowledge problem Lynch calls "the reader knows everything I know except this one thing." His Docker example is perfect: a writer explaining Docker by referencing Linux cgroups and BSD jails is writing for themselves, not their audience. The rewrite strips jargon and explains what Docker actually does. It's the kind of edit that looks obvious after someone shows you, which is exactly the point. Lynch's link-dependency argument is the most counterintuitive entry. Developers treat hyperlinks as inline footnotes — slap a link on an unfamiliar term and move on. Lynch points out that linking to a 20,000-word FreeBSD manual chapter to explain one concept is dumping work on the reader. The fix: give the minimum viable explanation inline, then link as a bonus. This reframes links as supplementary rather than load-bearing, which is a genuine craft insight. The "sequel injection bug" names something every blog reader recognizes but nobody talks about. Posts that open with "In part one, we learned..." impose homework on the reader before they've committed to reading. Lynch's rule — most sequel posts could be standalone with 3% more effort — is the kind of ratio that sticks in your head. The formality section leans hard on Joel Spolsky as the gold standard of software voice, and it's the right call. Lynch quotes a Spolsky passage about CS students hitting pointers and switching to Political Science — casual, specific, funny, zero pretension. The implicit argument is that AI-generated writing is making human voice more valuable, not less. Write like you talk, not like a legal filing. The HTML rendering sections (mobile overflow, font contrast) are shorter and more prescriptive. They're less interesting as writing advice but genuinely useful: 25-35% of readers are on mobile, and many developer blogs break on phones because nobody checks. Lynch names the specific tools (Firefox/Chrome mobile preview, accessibility contrast checkers) and the specific free font (Atkinson Hyperlegible from the Braille Institute). What makes this work as a whole is that Lynch practices what he preaches. The post is structured exactly the way it tells you to structure posts: clear thesis up front, named sections, concrete examples with before/after rewrites, no meandering. It's a style guide that doubles as a demonstration of the style it's advocating.
