Written communication tips for effective software developers

Monday, August 13, 2018

Giving the reader the choice to stop reading

Sometimes you have to send one email to lots of people with very different levels of context, knowledge, and interest.

Sometimes you just can’t decide between keeping it short to be objective or explaining in details to avoid ambiguity.

Sometimes you want to focus on communicating a short statement but want to include more information that people will use for future reference.

How to solve all these dilemmas? Give the reader a way out.

The reader should have the option to stop reading when they feel it is not for them anymore. Your job is to make it easier for them to notice when is a good time to quit reading your email.

You do that by writing your text with progressive depth. You start with the most important message that everyone reading the email should get. For example, informing that a new feature is live.

Keep it short, one or two sentences, then skip a line and start the next paragraph. The next paragraph should explain in a few lines what feature does in more detail.

Then you can add more paragraphs explaining what the original problem that feature is solving is, or how to use that feature (if there are users of your software among the recipients). You can add more context about how does it fit the company-wide strategy, and so on.

Be explicit when you are entering in optional content.

When moving into new paragraphs, make it clear who should read it and when. Include introductions like '“If you need more context…”, “More information for those who were not in the meeting…”, “Here are some details for future reference...”, etc.

Written communication tips for effective software developers