Industry Commentary →

The Technical Writing Anti-Patterns That Matter When Your Reader Is an Executive

Simon Willison flagged Michael Lynch's advice on software blogging anti-patterns. Here is what changes when the audience shifts from technical peers to the CEO, board, or PE partner making the capital allocation decision.

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.

Frequently Asked Questions

Why does technical writing fail for executive audiences even when it works for engineers?

Because technical writing is typically optimized for the reader who already shares context — someone who knows the codebase, the architecture, the constraints. Executives don't share that context, and they can't stop to click a link or fill in gaps from memory. When a technical document assumes shared context, it creates a comprehension gap that executives compensate for by either ignoring the document or making a decision based on the parts they did understand, which are usually the wrong parts. The fix is not simplification — it is reframing. Lead with the financial or operational consequence, not the technical mechanism. The architecture diagram that convinced a board to approve a $20 million modernization did not hide complexity. It made complexity visible in a way that made the decision clear.

What are the most common anti-patterns when engineers write for business leaders?

Three stand out consistently. First, starting with the technical problem rather than its consequence — engineers write 'the system has a latency issue' when the reader needs 'customers are waiting 12 seconds at checkout and it is costing the business $340K per quarter.' Second, using technical terms without anchoring them to business impact, so the executive either skims past or decides the document is not for them. Third, burying the recommendation at the bottom after a long setup — executives read the first paragraph and skim for the ask, so the document structure needs to invert the engineering instinct. The recommendation and its stakes go first; the technical justification follows for the readers who want to verify it.

How should engineers adapt their communication style for board or C-suite presentations?

Three adjustments cover most of the gap. First, lead with consequence in the opening sentence — what happens if this decision goes wrong and what it costs. Second, one visual that a non-technical reader can absorb in under 30 seconds — not an architecture diagram for engineers, but a diagram that shows the decision path and what is at stake at each branch. Third, a clear recommendation with a number attached: 'We recommend option A because it reduces risk by X and costs Y less than option B over 18 months.' Executives are not avoiding technical depth — they are looking for someone confident enough to synthesize it into a recommendation. Engineers who can do that earn access to higher-stakes decisions.

Shawn Livermore — Fractional CTO & Chief AI Officer
About the Author

Shawn Livermore

Fractional CTO and Chief AI Officer with nearly 3 decades of enterprise architecture experience. Clients include Kelley Blue Book, LERETA ($18B property tax processor), First American Financial, Carvana, WellPoint/Anthem, and PacifiCare. 92 client reviews, 5-star average.

View full background →

Need a fractional CTO or CAIO?

Technology leadership without the full-time headcount. Engagements start with a conversation.

Man writing a flowchart diagram on a whiteboard with a blue marker.