Technical Writing Is an Engineering Skill

TL;DR — Technical writing isn't a soft skill adjacent to engineering; it's the same skill as API design, applied to a human reader. It's also the only artefact you produce that keeps working when you're not in the room. Five rules do most of the work: lead with the conclusion, name the rejected alternative, numbers not adjectives, write the decision not the journey, write for the person who joins in a year. The highest-frequency writing you do is the PR description, and most engineers waste it. The test for any of it: can someone act on this without asking you a question?

Why it's an engineering skill

Consider what you do when you design an API. You decide what the caller needs to know and what you can hide. You name things so the next person guesses right. You pick the smallest surface that solves the problem. You anticipate misuse.

Now consider what you do when you write a design doc. Exactly that, for a reader instead of a caller.

Same discipline, same failure modes. An unclear document is an API with bad naming and no docs — technically complete, practically unusable.

There's a second reason it belongs in the engineering column: leverage. Everything else you produce is bounded by your presence. Code you wrote needs you to explain it. A decision you made verbally needs you in the meeting to defend it. A document is read by people you'll never meet, in years you're not there, answering questions nobody thought to ask you. It's the only thing you make that compounds without your attention.

Five rules

1. Lead with the conclusion

Engineers write mystery novels: background, investigation, three options, and the answer on page four. It feels rigorous. It's actually a failure to prioritise the reader over the process.

❌ We evaluated three approaches to offline sync…
   [800 words] …therefore we recommend the outbox pattern.

✅ We're using the outbox pattern for offline sync.
   It costs one extra table and ~200 lines; it's the
   only option that survives process death mid-write.
   Reasoning and rejected alternatives below.

Most readers needed the first two sentences. The people who need the reasoning will keep reading — they were always going to. You lose nothing by putting the answer first and you save eight people ten minutes each.

2. Name what you rejected, and why

A document that presents one option reads as unconsidered, however much work went into it. And it will be re-litigated in six months by somebody who has just thought of the thing you dismissed on day two.

One line each is enough:

Rejected: last-write-wins. Simplest, but silently
discards edits — we'd never see the data loss.

Rejected: CRDTs. Correct, but three weeks and a
dependency nobody on the team has debugged.

That section does more to establish your judgement than the recommendation does. It's also the part that saves the most time later, because it shuts down the re-litigation before it starts.

3. Numbers, not adjectives

"Slow", "clean", "scalable", "significant" are all opinions wearing technical clothing. They can't be disagreed with, which means they can't be discussed.

❌ Startup is slow on older devices.
✅ Cold start P95 is 3.4s on a Galaxy A14 (Android 13).
   Budget is 1.5s. 38% of our users are on comparable
   hardware.

The second version is arguable, which is the point. It also survives the transition from your head to someone else's.

4. Write the decision, not the journey

Your two weeks of investigation are not interesting to the reader, and including them is usually about demonstrating effort rather than informing.

The reader wants: what did you decide, why, and what does it cost. Not the six dead ends. If a dead end is genuinely instructive — you tried the obvious thing and it failed for a non-obvious reason — that belongs in the rejected-alternatives section as one line, not as a narrative.

5. Write for the person who joins in a year

This is the rule that changes the most. Everyone currently in the room already has the context; they are the worst possible audience to optimise for, and they're the only one you can see.

The real reader is someone six months from now, on a different team, who found this document from a code comment, at 2am, during an incident. They don't know your acronyms. They don't know who "the platform team" was in 2026. They need to know what to do.

Expand the acronym once. Link the ticket. Say what something is before you say what you did to it.

The four documents worth being good at

The PR description. By far your highest-frequency writing, and mostly wasted on a restatement of the diff. What it should carry:

## What
Retry policy on the sync worker: exponential backoff, max 5.

## Why
APP-4412 — 3% of syncs fail on flaky networks and never retry.
Users see stale data until they force-close.

## Instead of
WorkManager's built-in retry: it doesn't distinguish 4xx from
5xx, so we'd retry auth failures forever.

## How to verify
Airplane mode mid-sync, restore after 30s → sync completes.
Unit test: SyncWorkerTest.retriesOnTransientFailure

## Risk
Retries hold an IO thread. Bounded to 4 concurrent.

Four minutes. It makes review faster, archaeology possible, and the 2am revert decision obvious.

The ADR. One decision, one page, dated, with the rejected options. Its value is almost entirely in year two, when someone asks "why on earth is it like this" and the answer exists.

The postmortem. Timeline, contributing causes, what we're changing. Blameless in the sense of naming systems rather than people — but it must still name a cause. See below.

The migration guide. If you're asking other teams to change code, the doc is the product. Before/after, mechanical steps, deadline, owner.

The failure mode: writing to protect yourself

The worst engineering documents aren't badly written. They're defensive — written so that no statement can later be held against the author.

It produces postmortems where the cause is "a combination of factors", design docs where every option is "viable depending on requirements", and status updates where nothing is late but nothing has shipped.

Everyone can tell. And it costs more credibility than the mistake being hedged around ever would, because now the reader is uncertain about both the incident and your account of it.

The alternative is to commit: "This happened because we didn't have a timeout on the licence call. I added one. We should audit the other external calls, and I've filed APP-4501 for it." That paragraph makes you look better than four paragraphs of context-setting, and it's shorter.

Two practical things

One page beats five. Nobody reads five. If it must be long, the first page has to stand alone — assume that's all anyone read, because for most of your audience it is.

Write it before you build it, not after. A design doc written afterwards is a description. Written first, it's a thinking tool, and it routinely kills bad ideas for the price of an afternoon. The number of times I've abandoned an approach halfway through writing it up is the strongest argument for the practice.

The rule

If you can't write it down, you don't understand it yet — and if you don't write it down, it only ever helps the people who were in the room. Lead with the answer, name what you rejected, use numbers, and write for the stranger at 2am. It's the same skill you already have; you're just pointing it at a reader.