Writing for Clarity
The habits that made me a better technical writer — and a better engineer.
I spent years thinking writing was a soft skill tangential to engineering. I was wrong.
The engineers I've learned the most from — the ones whose code reviews I looked forward to, whose design docs made complex systems click — were all good writers. Not fancy writers. Clear ones.
Clear writing is clear thinking
The most useful thing writing has done for me is expose fuzzy thinking. If I can't explain a design decision in plain sentences, I don't understand it well enough. The act of writing forces me to confront what I actually know versus what I vaguely believe.
This applies everywhere: PR descriptions, Slack messages, ADRs, documentation. Each one is a chance to think more clearly.
Cut ruthlessly
The first draft of anything is too long. Technical writing especially tends to bury the useful parts under qualifications, context, and hedging.
Before you publish or send, ask: what is the one thing the reader needs to know? Put that first. Then cut everything that doesn't support it.
A short clear message beats a long thorough one that nobody reads.
Concrete over abstract
Abstract: "The system handles load efficiently."
Concrete: "The system handles 50,000 requests per second at p99 < 10ms on 4 cores."
Numbers, examples, and specific outcomes are always more useful than adjectives. When you catch yourself writing words like "robust", "scalable", or "efficient", stop and replace them with evidence.
Write the boring stuff
The most impactful writing I do isn't blog posts. It's:
- PR descriptions that explain why, not just what
- Comments that explain the invariant a piece of code relies on
- Runbooks that future-me will actually use at 2am
- Design docs that capture the options we considered and why we chose against them
This is the writing that compounds. It makes teams faster because it reduces re-explanation and onboarding time.
Start before you're ready
I used to wait until I had something perfectly formed before writing it down. Now I write early drafts while I'm still thinking through a problem. The writing itself shapes the thinking.
Start with a sentence. Finish it. Write the next one. Revise later.
The best investment I've made in my engineering career wasn't a new language or framework. It was getting better at writing. Everything else got easier after that.