Technical Writing for People Who'd Rather Write Code
Updated: 1 day ago
You write more than you think: PR descriptions, commit messages, design docs, incident reports, READMEs, chat messages, and updates for people who don't know what a message queue is. Most of it is read by people who weren't in your head when you wrote it.
That's the whole difficulty. Writing advice usually comes as rules (short sentences, active voice, no jargon), and the rules are fine. But a document can follow every rule and still fail, because the problem isn't style. It's that the writer can't see what the reader is missing. This post starts with a way to see it, and then gets to the rules, formats and examples.
Why you can't see what your own document is missing
In 1989, Colin Camerer, George Loewenstein and Martin Weber described the curse of knowledge: people who know something find it hard to imagine not knowing it, even when they try and even when it costs them. Their experiments were about economic judgments, but the mechanism is familiar to anyone who has reread their own design doc and found it perfectly clear.
When you reread your own writing, your memory supplies everything the page leaves out: the constraint you discussed in a meeting, the abbreviation everyone on your team uses, the reason option B was ruled out last month. The page seems complete because you're reading it with the context attached. The reader gets only the page.
So the fix isn't to try harder to imagine the reader. It's to get a real reader and watch what happens.
The test: reread the last document you sent and underline every term, acronym or decision that depends on something not written in it. Most writers find three or more on the first try, and that's with the curse still working against them.
The cold-reader test
This is the most useful habit in this post, and it takes five minutes. Before sending anything that asks people to decide or act (a design doc, a proposal, an incident summary), give it to one person who wasn't involved. Give them five minutes, then ask three questions without letting them look back:
What's being decided or proposed?
What do you need to do, and by when?
What's the main risk or open question?
If they answer all three correctly, send it. If they can't, the gap is in the document, and their wrong answer usually tells you exactly where.
A running example (composite). An engineer writes a design doc proposing retries for calls to a payment provider, which time out on about 2% of requests. The first draft opens with three paragraphs of history: when the integration was built, two earlier incidents, how the timeouts were investigated. The proposal appears on page two. The decision needed from the platform team (whether to allow a retry library in the service) is in the second-to-last paragraph.
She gives it to a colleague from another team for five minutes. The colleague says the doc is "about payment timeouts", can't say what's being proposed, and guesses the ask is for more monitoring. She rewrites. The new version opens with: We propose retrying timed-out payment calls up to 3 times with exponential backoff, using idempotency keys so a retry can't charge twice. We need the platform team to approve the retry library by 14 March. A second cold reader answers all three questions correctly. The review meeting she had booked to explain the doc gets cancelled.
The test: run the three questions on your next document before you send it. Keep a tally for a month of how often the first draft passes. It's usually lower than writers expect, and it rises quickly once you start writing for the test.
Lead with the point
The fastest way to pass the cold-reader test is to put the answers to its three questions in the first paragraph. Engineers tend to write in the order they worked: background, investigation, options, conclusion. Readers need the reverse.
Built up: "We've been evaluating several options for the caching layer. After considering Redis, Memcached and an in-process cache, and taking into account our consistency requirements, operating overhead and team familiarity, we've decided to go with Redis."
Point first: "We're using Redis for the caching layer. It meets our consistency requirements and the team already runs it. The full comparison is below."
The reader who trusts you can stop after two sentences. The reader who wants to check your reasoning knows what they're checking. Nielsen Norman Group's eye-tracking research on how people read on screens supports the same layout: most readers scan, so the important points belong in the first two paragraphs and in the first words of headings.
The test: cover everything except the first paragraph. Does it alone tell a reader what you want and why? If not, move the conclusion up.
Sentences and words: the rules, with their reasons
Google's technical writing course, written for engineers, gives the reasoning behind the usual rules rather than just the rules. Three are worth adopting.
One idea per sentence. Google's guide compares a sentence to a program statement that does one thing. When a sentence carries a list, turn it into a bulleted list.
Cut filler. "Shorter documentation reads faster than longer documentation", and every extra line is another place for the text to go out of date.
Replace vague words with numbers. Hedges such as "somewhat", "relatively" and "arguably" add uncertainty without information.
The last one has the biggest effect in engineering writing:
Vague | Specific |
"The service is somewhat slow, probably because of the database." | "The service responds in 800 ms at p95. Database queries take 600 ms of that; the filtered columns have no index." |
"The new approach should handle concurrency better." | "If two users update the same order at once, the second update now fails with 409 Conflict instead of silently overwriting the first." |
"We'll roll this out soon." | "We'll enable it for 5% of traffic on 3 March and for everyone on 10 March if error rates hold." |
If you don't know the number, say so: "we haven't measured this yet" is more useful than a hedge, because it tells the reader what to ask for.
The test: search your draft for "somewhat", "relatively", "fairly", "should", "soon" and "better". Each one either becomes a number, a date or a condition, or comes out.
Structure for people who scan
Most people reading a technical document are looking for one thing: the decision, the command, the section that affects them. Structure is what lets them find it.
Headings that say the answer, not the topic. "Retries are capped at 3 attempts" is findable. "Retry considerations" isn't.
Lists for anything that's a list. Steps, options, requirements.
Code blocks for anything a reader might copy.
Short paragraphs, each doing one job.
The test: read only the headings and the first sentence of each section. If that skim gives a reader the gist and lets them find the part they need, the structure works. If the headings could belong to any document on the subject, rewrite them as statements.
Formats that do most of the work
Most engineering writing falls into a few formats, and each has a shape that already passes the cold-reader test.
PR descriptions
A reviewer needs to know what changed, why, and where to look first.
## What
Retry timed-out payment calls, up to 3 attempts with exponential backoff.
## Why
About 2% of calls to the payment provider time out and currently fail
permanently, so support retries them by hand. Idempotency keys make a
retry safe: the provider ignores a duplicate key.
## How to review
- Start with PaymentClient.cs; the retry policy is applied there.
- RetryPolicy.cs is the generic backoff implementation.
- Tests cover backoff timing, the attempt cap and the duplicate-key case.
The "how to review" section is the one most often missing, and it's the one that decides whether the review teaches anyone or just gets skimmed.
Commit messages
Git's own documentation recommends starting with a single short line of no more than 50 characters, then a blank line, then a fuller description. Git treats the first line as the commit's title and uses it throughout, including as the subject line when a commit becomes an email. Chris Beams' widely used guide adds the rest of the conventions: capitalise the subject line, don't end it with a period, use the imperative mood ("Add retries", not "Added retries"), wrap the body at 72 characters, and use the body to explain what and why rather than how.
Retry timed-out payment calls
About 2% of payment calls time out and fail permanently. Retry up to
3 times with exponential backoff (1s, 2s, 4s). Idempotency keys make
retries safe to repeat.
Closes #1234
"Fix bug" isn't a commit message. Six months later, someone running git log on that file needs the why.
Design docs
Malte Ubl's description of design docs at Google gives a structure that works well outside Google: context and scope, goals and non-goals, the design itself, alternatives considered, and cross-cutting concerns such as security, privacy and observability. He calls alternatives considered one of the most important sections, because it shows why the chosen design fits the goals better than the others. Without it, reviewers invent their own alternatives and the review turns into relitigating them.
He's also clear about when not to write one. If the problem isn't ambiguous, and the doc would read like an implementation manual with no trade-offs, writing the code is usually better. For decisions that need a permanent record, an architecture decision record is the lighter format.
The test: for your next design doc, check that the non-goals and the alternatives sections both exist and both say something a reasonable colleague might disagree with. If they don't, either the problem isn't ambiguous enough for a design doc, or the hard part hasn't been written down yet.
Writing for people who don't write code
Updates for managers, product owners and executives fail in a predictable way: they describe the work, when the reader needs to know what changed for them. Use the same point-first structure with the reader's units.
Describes the work: "We refactored the payment client and added an exponential backoff retry policy with idempotency keys."
Says what changed for the reader: "Failed payments that support used to retry by hand, about 40 a day, now retry automatically. Customers will no longer see a payment error for a provider timeout. No action needed from you; we'll confirm the drop in support tickets in two weeks."
The second version passes the cold-reader test for a non-engineer: what happened, what it means for them, what they need to do (nothing), and when they'll hear more. The status report template gives a recurring version of the same structure.
The test: give your next update to someone outside engineering and ask what changed for them. If they repeat your technical description back, rewrite it in terms of customers, money, time or risk.
When AI drafts it
AI tools are good at producing fluent first drafts, summaries and tidy formatting. They can't run the cold-reader test for you, because they don't know what your reader is missing either, and they'll fill gaps with plausible text. Treat an AI draft like any first draft: check every claim and number against the source, then give it to a cold reader. A fluent document that answers the wrong question still fails the test. If you're writing documentation that has to stay useful over time, documentation that people actually read covers the maintenance side.
What to do this week
Pick the next document you'd send for a decision. Before sending it, run the cold-reader test with one colleague for five minutes. Fix whatever they got wrong, which usually means moving the decision and the ask into the first paragraph. Then search the draft for vague words and replace each with a number, date or condition. For the rest of the week, write every commit subject in under 50 characters, imperative mood, with the why in the body.
Final takeaway
You can't see what your own writing leaves out, because your memory fills the gaps. So don't rely on rereading: give the document to someone cold, ask what's being decided, what they need to do and what the risk is, and fix whatever they miss. Put the answers to those questions first, replace vague words with numbers, write headings that state the answer, and use the formats (PR descriptions, commit messages, design docs) that already have the right shape.
Sources
Camerer, C., Loewenstein, G. and Weber, M., "The Curse of Knowledge in Economic Settings: An Experimental Analysis", Journal of Political Economy 97(5), 1232–1254 (1989). https://doi.org/10.1086/261651
Google for Developers, Technical Writing One, "Short sentences": focus each sentence on a single idea; convert long sentences to lists; "Shorter documentation reads faster than longer documentation." https://developers.google.com/tech-writing/one/short-sentences
Pernice, K., "F-Shaped Pattern of Reading: Misunderstood, But Still Relevant" (Nielsen Norman Group, 2017; pattern first identified 2006): users mostly scan; put the most important points in the first two paragraphs and start headings with information-carrying words. https://www.nngroup.com/articles/f-shaped-pattern-reading-web-content/
Git documentation, git-commit, DISCUSSION: begin with a single short line of no more than 50 characters, a blank line, then a fuller description. https://git-scm.com/docs/git-commit
Beams, C., "How to Write a Git Commit Message": the seven rules. https://cbea.ms/git-commit/
Ubl, M., "Design Docs at Google" (Industrial Empathy, 6 July 2020): sections, the importance of alternatives considered, and when not to write a design doc. https://www.industrialempathy.com/posts/design-docs-at-google/
Related reading
Keep learning. This article is part of the Project Delivery & Change Management path in the ShiftQuality Learning Center. Ship change without breaking trust or production.
