On Writing Well

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.

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.

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”

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

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

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.