Writing Better
Engineers write constantly.
Slack messages explaining why the build broke. Design docs arguing for architectural decisions. Technical documentation that onboards new team members. Code comments that justify the hack. Pull request descriptions. Incident reports.
The quality of this writing shapes how effectively you work with others and how your ideas spread.
I’ve been working on improving my writing, from blog posts to commit messages. Here are the principles that have helped me most.
DO
1. Vary your sentence rhythm.
Set the pace with sentence length. Short sentences create urgency. Longer ones build flow and give readers room to breathe, establishing rhythm that pulls them through your argument or story.
Read your work aloud. You’ll catch clunky sentences, awkward phrasing, repetitive language.
2. Start strong.
Your opening must earn the reader’s attention. If the first sentence doesn’t make them want to read the second, you’ve already lost them.
Drop them into action, a question, or something surprising. Never open with throat-clearing.
3. Be specific and concrete.
Dig for concrete details that appeal to the senses.
Instead of “He showed satisfaction as he took possession of his well-earned reward,” write “He grinned as he pocketed the coin.”
Concrete details create pictures. Abstractions create fog.
4. Cut ruthlessly.
A sentence should contain no unnecessary words, a paragraph no unnecessary sentences—for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts.
A good rule of thumb: your second draft should be 10% shorter than your first.
5. Use active voice.
Passive voice feels safe, but it’s weak. Instead of “The meeting will be held at seven o’clock,” write “The meeting’s at seven.”
Active voice shows who did what and keeps sentences energetic.
6. Create tension and forward motion.
To propel readers forward, make them wait. Use internal cliffhangers and plant clues early.
Even non-fiction needs a reason for readers to continue. Give them a question that the writing will answer.
7. Write naturally, then edit.
Use words and phrases that come readily to hand. Any word you have to hunt for in a thesaurus is probably the wrong word.
DON’T
Don’t bury the point.
Begin sentences with subjects and verbs. Make meaning early, then let weaker elements branch to the right.
If readers have to dig for why they should care, they won’t.
Don’t over-explain.
Trust your reader’s intelligence. Ornate prose and overstatements alienate readers.
Don’t lean on adverbs.
If you wrote “He closed the door firmly,” shouldn’t the context already tell us how he closed it? If so, ‘firmly’ is redundant.
Weak verbs propped up by adverbs feel flabby. Strong verbs stand alone.
Don’t be predictable.
Seek original images. Reject clichés and first-level creativity.
Clichés and formulaic structures signal autopilot—so the reader checks out too.
Don’t forget white space.
Easy-to-read writing contains lots of short paragraphs and white space.
Dense walls of text exhaust readers. Paragraphs are breathing room.
The simplest test: Would I keep reading this if I didn’t have to?
Why This Matters for Engineers
These principles apply everywhere you write.
In Slack: “The deploy failed” is passive and vague. “I broke the deploy by merging #1234 without running integration tests” is active and specific. Your team can act on the second message.
In design docs: Start with the decision you’re proposing, not the history of how you got there. Bury your thesis on page 3, and nobody reads it.
In code comments: Don’t explain what the code does. The code itself does that. Explain why. Why this approach over alternatives? Why this edge case matters? Why this looks weird but is correct?
In technical writing: Cut the jargon you can avoid. Keep the jargon you can’t, but define it. Concrete examples beat abstract explanations.
The same principles that make a blog post readable make a design doc persuasive and a Slack message actionable. Writing is thinking. When your prose is muddy, your thoughts probably are too.