Technical Writing for Engineers Who Hate Writing

A lot of engineers treat writing as a chore bolted onto the real work, which produces documentation that reads like it was written under protest: terse to the point of unhelpful, or padded with boilerplate to look complete. Neither serves the reader. Here's a more useful way to think about it.

Write for the reader who's stuck, not the reader who already knows

Documentation is mostly read by someone trying to solve a specific problem right now, often under time pressure: a new team member setting up their environment, an on-call engineer debugging an incident at 2am, a future version of you who's forgotten the details. Write with that reader in mind: what do they need to know to unblock themselves, in the order they'll need it, without requiring them to already understand the system.

Lead with what something is for, not just what it does

A README that opens with installation steps skips the question a first-time reader actually has: should I even be using this? A short paragraph on what problem the project solves and when you'd reach for it, before the setup instructions, saves readers who aren't a fit from wasting time, and orients the ones who are.

Show the command, not just the description

"Run the setup script to install dependencies" is less useful than the actual command: npm install && npm run setup. Whenever a document is describing an action a reader needs to take, include the literal command, config snippet, or code, not just a prose description of it. Readers copy-paste; they don't want to reconstruct your description into working syntax.

Document decisions, not just implementation

A design doc that only describes what was built misses the most valuable part for future readers: why it was built that way instead of the alternatives. Briefly noting what other approaches were considered and why they were rejected saves the next person from re-litigating a decision that was already made deliberately, and helps them judge whether the original reasoning still applies when circumstances change.

Keep examples runnable and current

An example that no longer works because the API changed is worse than no example, because it costs the reader time discovering it's wrong before they realize they need to look elsewhere. Where possible, keep examples close to actual tested code rather than hand-written prose approximations, so they're more likely to get updated when the underlying code changes.

Write the doc while you still remember why

The clearest documentation is usually written immediately after finishing the work, while the reasoning and edge cases are still fresh, not weeks later from memory. If you can't write it immediately, at least jot rough notes on the non-obvious decisions so you're reconstructing from notes rather than from scratch later.

Try the Technical Writing module to draft documentation, READMEs, or design docs from a rough outline, free for your first 5 responses.