Write to be understood

Communication is difficult and that is why misunderstandings happen. Some people feel that they have “communicated it” when they have “told someone”. In my opinion that is too easy. Making sure someone understands your point of view is for a large part the responsibility of the person sending a message. And that responsibility includes seeking confirmation if what was communicated is also understood.

In teams that may be difficult though. The media that we use to communicate (Email, chat apps like Slack or Telegram, collaboration platforms like GitHub or Jira, or in person meetings and video calls) greatly influence how we are going about our communication. They constrain us. Sometimes these constraints enable us but sometimes lead us towards poor communication.

Here are some of the things I tell myself and others to improve written communication (in no particular order):

NOT instead of not

Negation is a powerful language construct. But using it in written language may cause it to be overlooked. Especially in longer sentences. That is why I always uppercase NOT to ensure that it stands out.

Readable handwriting

Yes, ever since the keyboard entered our lives we lost our handwriting ability. This is so bad that I often joke about this when training people:

Participant: “Sorry Marijn, I can’t read what I wrote down here..”

Me: “I know, no one else can either. This training is secretly just handwriting practice. The DDD stuff you get for free ;-)”

As much as we may ridicule our own handwriting, we should just write it down again if something is not legible. Take your time to do so. When I’m facilitating a workshop I sometimes try 3-5 times to write something down in a legible and understandable way.

Standardization helps to a point

Certain things can easily be written in a standard, structured format. For example the BDD narrative (as an X, I want Y, because Z) or the ADR format (In the context of <use case/user story u>, facing we decided for

These structured forms are great to make sure you are NOT missing anything. The problem is that they bore the reader to death. If you have to read three of these “stories” consecutively you might find yourself in need of another coffee.

That is why I often try to write in simple terms and use these structured formats as a checklist to see if all the elements are there. I like my rules as guidelines: they should serve a goal and NOT become the goal.

Rewrite when mistaken

So you realize that something you wrote on that sticky note is wrong. Do NOT just correct on the post-it note. Write a new one instead so that the burden is on you and not on the reader.

Visually attractive, recognizable and coherent

If we want people to read it than it helps if it is visually attractive. It is not about the aesthetics but it is about conveying the important parts. The importance of your message should be visually recognizable (thanks to using whitespace, underlining, highlighting and doodling) and that should be coherent with what you are trying to communicate. In other words: write important things BIG, use green for success and red for error, use common iconography to support what you say with visuals.


Share your before and after pictures with me on Twitter, I’m curious to see your improvements :-)