Books for software engineers and managers

On Writing Well

The Classic Guide to Writing  Nonfiction

by William Zinsser

Categories:
Favorite,
Engineering Manager,
Tech Lead,
Star Engineer,
Product Manager

Clear thinking becomes clear  writing

Code reflects our thinking. Muddy code comes from muddy thoughts. We call prototypes “throwaways” because they reflect volatile thinking.

Although clear writing necessitates clear thinking, the act of writing itself can deliver both.

Writing is a powerful search tool, helping authors bring clarity to fuzzy thinking.

Write for yourself, not an imaginary  audience

When you imagine your audience, you’ve introduced a new job to the act of writing. Not only are you responsible for putting clear words on paper, but now those words must also match the mood and mindset of an imaginary audience.

Write for yourself instead. The words will flow.

Things to avoid

On Writing Well contains a series of small and practical techniques everyone can apply right now to improve their writing:

  1. Remove non-conversational language: Indeed, we found the root cause…
  2. Remove qualifiers: I was a bit confused…
  3. Remove value declarations: Surprisingly, we found the bug in our API.
  4. Remove clichés: Let’s think outside the box.
  5. Stop waxing poetically: She programmed effortlessly, beautiful code flowing down the page solving a myriad of bugs simultaneously.
  6. Favor active over passive verbs: “The bug was reproduced” vs. “I reproduced the bug”

Leave the reader with one provocative  thought

Have an opinion. Make an unpredictable observation. Include a surprise.

Above all, give me a reason to read your writing.

Focus on how the situation affected you, not what you  did

This advice is particularly useful for post-mortem authors.

You know the phrase, “Just the facts, ma’am”? That’s stupid advice.

When I read a post-mortem, I care less about the facts and more about the effect of those facts on the people and systems involved.

Write about the impact of the situation using conversational language.

On Writing Well

How strongly do I recommend On Writing Well?
10 / 10

The advice in On Writing Well applies directly to programming and I highly recommend this book for every software engineer.

Not only will your code improve in clarity and readability, applying the guidance from On Writing Well will improve every all of your written communications – Slack messages, emails, post-mortems, documentation, performance reviews, and the list goes on.