Engineers like to think of code as something you refine. You remove what isn’t needed, simplify what is, and try to leave it in a state where the next person doesn’t have to struggle to understand it.

And then we sit down to write.

The document fills up quickly. A few hedges, a few qualifiers, a sentence that sounds professional but doesn’t quite say anything. You’ve probably written something like:

We might want to consider potentially optimizing the query performance in some cases.

What it usually means is:

This query is slow.

Somewhere along the way, the point gets diluted because writing doesn’t feel as strict as code. It should. The same instincts apply.

Zinsser’s argument in On Writing Well is straightforward: most writing is cluttered. It carries more than it needs to. Words accumulate the way unused code does. Nothing breaks, but everything becomes harder to follow.

The fix is well known to engineers. Remove what doesn’t contribute.

You can see it in small edits:

The system is, in a sense, experiencing a bit of a latency issue.

becomes

The system is experiencing latency.

Nothing important was lost. It just stopped making the reader work.

But editing only gets you so far. Most of the time, unclear writing points to unclear thinking. The page is just where that shows up.

This is especially obvious in design docs. You’ll read an explanation that sounds reasonable, but doesn’t quite hold your attention:

This solution provides better scalability and flexibility for future use cases.

It’s hard to argue with, but it’s also hard to evaluate.

Compare that to:

We chose this because write throughput is our bottleneck, and this reduces write amplification by 40%.

Now the reader has something concrete to react to. The difference is clarity of thought.

One habit that helps more than expected is reading your work out loud. On the screen, a sentence can look fine. When you hear it, the problems stand out. You notice where it drags or repeats itself, where it feels longer than it needs to be. If you run out of breath halfway through, the sentence is probably doing too much.

It also exposes tone. Sentences that sounded polished can come across as distant or mechanical. Good writing doesn’t need to sound casual, but it should sound like something a person could actually say.

Precision helps here. Weak verbs tend to hide what’s really happening:

The script quickly ran through the data and made improvements.

That leaves a lot open.

The script processed the data and reduced errors by 18%.

Now the action is clear, and the outcome is measurable.

You don’t need to invent a new style each time you write. Just like in code, there are patterns that already work. If you’ve read something that held your attention, it’s worth looking at how it was put together, how it moves from one idea to the next, how it avoids losing momentum.

What matters more is resisting the drift toward vague, overly careful language. It shows up most clearly in post-mortems:

An issue was encountered where the system experienced a degradation in performance.

It’s technically fine, but it keeps the reader at a distance.

The system slowed down.

Shorter, but also clearer and more direct.

Vague writing is rarely accidental. It’s often a way of avoiding a clear statement when the clear statement would be uncomfortable.

That’s really the thread running through all of this. Say what happened. Say what you mean. Remove what doesn’t help.

Good code does this without drawing attention to itself. You read it and understand the system without effort. Good writing works the same way. When it’s doing its job, you don’t notice the sentences. You follow the idea.

The reader can always tell when the writer did the hard thinking, and when they didn’t.

If you already care about clean code, the instinct is there.

Apply it to your writing.

If you found this helpful, please like or share it with a friend and consider subscribing if you haven’t already.

Thanks for reading,
Adlet Balzhanov

Connect with me on LinkedIn, just use the button below. I read every message. Cheers!

My LinkedIn

Takeaways from “On Writing Well”