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:
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.
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.