Simon Willison linked to a piece by Michael Lynch last week — Anti-Patterns in Software Blogging — that lists the habits that make technical writing fail: meandering introductions, over-reliance on links as a substitute for explanation, writing in a stiff formal register instead of the way you actually talk. Lynch’s list is accurate. Willison’s annotation adds one observation that landed: with so many developers delegating their writing to AI, software blogging is becoming blander and more homogenous — the anti-patterns getting baked in by default.
Both are writing for technical readers, for the engineer communicating with other engineers. What neither covers is the harder version of this problem: when the reader is a CEO, a board member, or a PE partner who is about to decide whether to authorize a $15 million modernization, an acquisition, or a technical hire they do not fully understand. At that point, all of Lynch’s anti-patterns still apply. Several others compound them into something much worse.
quadrantChart title Where Technical Documents Actually Land x-axis Low Clarity --> High Clarity y-axis Peers Only --> Executive Accessible quadrant-1 Board-ready quadrant-2 Glossy but shallow quadrant-3 Lost in jargon quadrant-4 Peer-readable only Meandering intro: [0.22, 0.28] Link instead of explain: [0.45, 0.22] Formal passive voice: [0.58, 0.18] Lead with consequence: [0.76, 0.74] The Livermore Report: [0.88, 0.91]
The rundown
Lynch identifies anti-patterns that plague software blogging: introductions that take three paragraphs to reach the point, assuming readers have followed every prior post, using links as a substitute for explanation rather than a supplement, and writing in the overly formal register that some engineers adopt when writing up-chain.
Willison’s link-post adds the observation that AI-ghostwritten technical writing defaults to exactly these patterns. Generative text produces the meandering hedge, the formal register, and the link-heavy citation style as default outputs. The floor for technical writing dropped; the ceiling did not rise.
Both analyses are aimed at engineers communicating with other engineers or a broader technical audience. That is worth solving. It is not the hardest version of this problem.
For the working software engineer
Lynch’s anti-patterns show up most damagingly in the documents that cross functional boundaries inside a company: architecture proposals, incident postmortems, vendor evaluations, and PRDs that are read by a mix of engineers and non-engineers, often skimmed in a review meeting, often used to justify a decision to someone up the chain.
Meandering intro kills architecture proposals. If the first paragraph is context-setting for engineers who already know the context, the PM or VP reading it has already disengaged. The document gets skimmed; its recommendation gets misunderstood.
Link-as-explanation kills postmortems. When an incident postmortem says “see the prior discussion about the cache behavior” with a link, executives have no prior discussion to reference. They read a document with gaps and conclude the team does not understand what happened.
Formal register kills credibility differently. Engineers sometimes adopt a passive-voice register when writing up-chain — “it was determined that the architecture would benefit from” — which reads to business readers as evasion. Direct, plain sentences read as confidence.
The practical fix: write your first draft for yourself, then rewrite the first paragraph as if the reader has never worked in software. That constraint reveals which sentences are doing real work and which are hedging.
For business owners and operators
Most technical documents that reach executive level were written for someone else and forwarded. The engineer wrote the architecture proposal for the engineering team; the VP forwarded it because you need to sign off. You are now trying to extract a decision from a document that was never designed to produce one.
The symptoms: you read the document, understand that something is complicated and expensive, but cannot tell whether the recommendation is right or whether there is a better option. You approve it because you have no basis to say no. Or you say no because it felt too expensive, without understanding what the alternative actually costs.
This is a communication design problem, not a people problem. The document was structured for the wrong audience at every level: the framing, the vocabulary, the placement of the recommendation, the missing financial stakes.
What you can do is name this directly. Tell your engineering leaders: when you bring a technical decision to me, I need three things — what happens if we do not act and what it costs, what you recommend and why, and what implementation costs. Everything else is supporting detail. Engineers who learn this format become significantly more effective in cross-functional settings — not because they are simplifying, but because they have learned to lead with the consequence.
My take
The moment I understood this most clearly was at LERETA, a property-tax processing company where I led a multi-year technology modernization. We needed board approval for a $20 million mainframe migration. The technical case was solid. The documentation was written for engineers. Executives were nodding but not committing.
The turning point was a set of wall-sized enterprise architecture diagrams — what became known internally as the “Livermore Report.” These were not architecture diagrams for engineers. They were visual representations of the entire critical path, designed to answer the question the board actually had: what are we committing to, what breaks if we do not, and what does the path forward look like?
The board approved the investment. The diagrams did not hide complexity — they made complexity visible in a form that matched how executives process information. Spatially, relationally, at a level of abstraction where the real decision points were visible and the consequence of inaction was clear.
Lynch is right that meandering introductions fail technical readers. For executive readers, the failure mode is different — it is the absence of any frame that tells them what the document is asking them to decide. Good technical writing for executives answers that question before it answers any technical question. The visual that does it in one frame is worth three pages of well-structured prose.