3 steps to write messages that people will enjoy reading

Your clear communication is more important than your clean code.

It's Monday morning, and you receive an email. The subject screams "Action Required". You jump in to read it. Once, then twice, but it remains unclear what you should do. Not being at your best on Monday mornings, you ask your colleagues, but they feel lost too.

I've experienced this too many times.

The author of the email should have made the message easier to understand. Instead, it raised questions and uncertainty.

As a staff engineering manager responsible for 5 technology units I've sent hundreds of important messages to hundreds of engineers. The quality of our communication influences the quality of our work.

Let's imagine that writing messages is like writing code. Just as code runs differently on machines with different versions of languages and libraries, different people can understand messages in multiple ways.

Unclear communication leads to problems and confusion. Clear communication helps with a better understanding of everybody’s responsibilities.

I’ve created a framework that will help you communicate clearly. It consists of 3 steps:

1. Prepare

2. Write it simply

3. Run a garbage collector

---

Anton here: when I wrote ‘The worst Slack messaging mistake engineers make’ I focused on empathy, and accepting your messages being ignored or misunderstood. With

Michał Poczwardowski

’s framework, you won’t need to worry about that! :)

I hope you’ll enjoy the (super useful) article, and I highly recommend you check out his awesome newsletter -

Perspectiveship

!

---

Framework

1. Prepare

You don't need to prepare if you’re writing for yourself, but writing for others is different. You’re unaware of what others know or think.

Think about the basics:

• Why are you writing the communication?

• What would you like to achieve with the message?

• Who is your audience?

Preparation is important. It is important for physical training to avoid injuries, and it is important for communication to make sure you consider the three basics above.

Why

There must be a reason why you started writing, it should be included in your message if it is important.

When the reason for your writing is to vent your frustration, it is better to wait until you have calmed down. Being aware of the purpose is the starting point for writing and setting its tone. You would write differently to celebrate success than to give a heads-up that the company is not doing well.

Anton here: asking “why do I write this message?” saved me from many damaging moments! Sometimes I completely re-write messages, when I understand that my goal is not to get into a fight, but to get the other person on my side.

Examples of possible reasons for starting to write a message:

• Because your team missed a deadline and you need to write an update to stakeholders.

• Because you are frustrated by the work of the supporting team and want to share feedback.

• Because a new bonus scheme is going to be introduced and you want to give your team a heads-up.

What

You have to know what your goal is so you can work towards achieving it. It is worth thinking about what is the goal of your message, to get the direction.

Imagine that your goal is to communicate that the team needs to level up their estimation skills, as they have been significantly off for the last three sprints. However, you end up just praising their good work with only a vague comment on estimation skills, and no reader sees it as an important issue after reading the message.

Examples of possible goals for starting to write a message:

• The goal is for your team to follow new rules.

• The goal is to successfully communicate the change.

• The goal is to share praise and make your employees feel recognised.

Who

When you write code, you know the language, its version, and the libraries to use. It is easy to predict the output. However, when writing for other people it’s difficult to predict their interpretations.

“We migrated to Flipper, a new feature flag gem on our Ruby backend.” This is clear for Ruby developers, quite clear for engineers (gems are Ruby libraries), but difficult to understand for non-technical people in the company.

Examples of different audiences:

• Business people in the company — non-technical and without an understanding of engineering.

• The support team — interested in learning all the scenarios that you have already tried out before engaging with them.

• Fellow managers — know most of the things that you know and have similar context.

• Your engineers — highly interested in what happens in your team, and technical.

Each of these example groups requires a different level of detail, different context and vocabulary — it is important to understand what they know.

The more you know about your audience the better because it helps you avoid things that they will not understand.

2. Write it simply

When you are speaking, you use much simpler words. Apply this to writing. It's because of a cognitive load, we want to be energy efficient when speaking. Complicated words and complex sentences use more brain resources than simple ones. When your reader is tired and low on brain resources, it is difficult to understand complicated communication. 

Simple words do not reflect a simple mind, it is the opposite.

What is easier to understand?

We are revising the protocol for merging pull requests: henceforth, a single approval will be requisite for a merge, as opposed to the previous stipulation of two. This adjustment reflects our increased confidence in your expertise and is intended to expedite our processes.

or:

Our brains think using stories. To lower cognitive load, write as the brain operates. Use an active form instead of a passive one. So, “I pushed to the production” instead of “The production has been updated by me”. It is easier for the brain to follow.

The style and structure of the message is important, and for more than a few sentences:

• Put the most important passage first.

• Organise it in a readable format — avoid a wall of text.

• Use three to four sentences per paragraph.

3. Run a garbage collector

Same as a garbage collector in the code, use your common sense and run it on your text. There might be plenty of words that do not add any important information, the fewer words you have the less processing power is needed to understand the message.

Simplification makes it easier to understand and saves time for readers.

Example: “We are changing the current rule for merging our pull requests: you now need at least one approval to merge your changes, instead of two approvals — we trust you, and we want to move our things a bit faster”

After removing (subjectively) unimportant words: “We are changing the rule for merging pull requests: you need one approval, instead of two— we trust you, and we want to move faster”

Every day, when I write simple messages using tools like Slack, I pause before clicking the send button and remove unnecessary words. In this article, I removed a few dozen words.

Summary

Prepare and think about why you need to write the message, what your goal is, and who your audience is. Then keep it simple and write as you speak. Finally, run a garbage collector and remove words that are not needed.

Remember that finishing your message on time is important, especially when people are waiting for it. Do not spend too much time on editing and at work you don’t aim for a Pulitzer Prize, you can keep it simple.

When the message has big implications, ask someone from your target audience to review it. It's important to understand others' perspectives, as with code reviews.

I wish you all clear communication!

Thanks for reading,

— Michał

PS Soon I’ll be doing 1-hour live workshops on communication dedicated to engineers and team leaders. Think of it as an extension of this article. It'll be available for free to

Perspectiveship

subscribers. If you are interested, subscribers will receive an email with details in the first week of August 2024.

Great resources on communication

1. Communicate like a Senior: How to write well by

   Jordan Cutler

2. 5 Writing Tips to Overcome the Blank Page by

   Akash Mukherjee

3. Signposting: How to reduce cognitive load for your reader by

   Wes Kao

4. On Writing Well: The Classic Guide to Writing Nonfiction by William Zinsser