Engineers who write well have a structural advantage. Their designs get reviewed by more people; their decisions stick because they're documented; their incidents produce learning rather than recurrence. Writing well is not a separate skill from engineering — it is part of the work.
This page is about the document types that matter, the patterns that make them useful, and the habits that turn writing into routine rather than ad hoc work.
Technical writing optimizes for the reader, not the writer. The reader has limited attention, may be reading later, may not have the context the writer has, and may not need every detail.
Specific principles that follow:
A design doc proposes a solution to a problem before implementation begins. The structure that works:
A good design doc is 2–10 pages. Anything longer is usually under-edited.
A runbook is operational documentation — what to do when something happens. The structure:
Runbooks are dramatically more useful than abstract architecture documentation in incident scenarios. The on-call engineer at 3am needs commands, not theory.
After an incident, a postmortem documents what happened and why. The structure:
The cultural element matters. Blameless postmortems — focused on systems, not individuals — produce learning. Blame postmortems produce defensiveness.
A short document capturing a single architectural decision:
ADRs are typically 1 page. They live alongside code; they preserve the why of decisions for future engineers who weren't around for the original choice.
A two-sentence summary at the top. The reader knows whether to keep reading.
Instead of "the system handles many request types" — list 3–5 specific request types with their characteristics. The abstract claim is forgettable; the specific examples stick.
A code block illustrating a pattern is worth a paragraph describing it. Where code can show what you mean, use it.
Architecture, data flow, dependency graphs are easier to understand visually. ASCII art is fine; Mermaid diagrams are better; even a hand-drawn diagram in a screenshot beats an abstract paragraph.
When you have N parallel items, list them. Embedding 5 items in a paragraph hides the parallelism.
"You should consider X" is weak. "Use X when Y; use Z when W" is actionable.
Before writing prose, write the section headings and the one-sentence summary of each. The structure should be apparent from the outline; if it isn't, the structure is wrong.
Don't edit while writing the first draft. Get the ideas out. The structural problems and missing details become visible after the draft exists.
Most first drafts are 20–40% too long. Cut sections that don't earn their place. Combine sections that overlap. Tighten sentences.
A senior engineer's feedback on a design doc is different from a junior engineer's feedback. Both are valuable; both reveal different blind spots. Get feedback from the actual readers.
Multiple drafts beat one polished attempt. The first draft establishes the shape; subsequent drafts make it sharp.
"Maybe we could perhaps consider..." — say what you think. If you're uncertain, say "this is uncertain because X."
Use precise technical terms when they're correct, but don't use jargon to sound expert when plain words work.
"As we all know, software systems have many components, and one important consideration is..." — get to the point.
A "conclusion" that restates the introduction adds nothing. Either say something new (a synthesis, a recommendation, next steps) or omit it.
"It was determined that..." — by whom? Active voice is usually clearer.
Some documents get written that probably shouldn't:
If a document type isn't producing value, stop producing it.
The engineers who write well typically:
Writing is a skill that improves with practice. Like any skill, the way to improve is the boring way: do it more, get feedback, revise.