Composing better emails (with examples from the software development world)

Email communication is not my favorite but since I can't avoid it, I am trying to compose messages in a way that I think it makes it easier for both me and the recipient:

• to quickly address what is being communicated
• avoid misunderstandings
• save time

Here are some tips. They don't apply to all type of messages, I provide before and after examples to better describe each case.

Emphasize text with bold/underlined font

Emphasizing the appropriate parts of a message, especially when it's a long one, you help readers quickly get an idea of what the email is about and easily locate the important stuff after going back to it at some point in the future.

Examples

Before

Hello all,

I noticed that there are many logs for blabla the last few days and I
 don't think that it is normal. I believe the problem is the updated 
version of gem blabla.

I have opened an issue describing the case in Redmine (#455) in the current version.
Feel free to change its priority in case blabla.

Thanks,
Lazarus

After

Hello all,

I noticed that there are many logs for blabla the last few days and
 I don't think that it is normal. I believe the problem is the updated 
version of gem blabla.

I have opened a Redmine issue (#455) describing the case in the 
current version.
Feel free to change its priority in case blabla.

Thanks,
Lazarus

Use specific dates instead of yesterday, tomorrow etc

The moment you send an email is not the moment that it will be read by its
recipients. Avoid using only temporal adverbs/nouns like yesterday,
today, tomorrow, two hours ago etc but include also the specific
dates/times otherwise they might be misunderstood or require from
recipients to check the email's sent date/time to calculate the actual
time.

Examples

Before

Dear QA,

Yesterday we released a fix for the bug 455 on staging and we plan to 
release it next Monday if you give us the green light by tomorrow end of 
day.

Thanks,
Lazarus

After

Dear QA,

Yesterday, June 25th, 2019 we released a fix for the bug 
#455 on staging and we plan to release it on production next 
Monday (July 1st, 2019) if you give us the green light by tomorrow 
(June 27th, 2019) end of day.

Thanks,
Lazarus

Use links for references

Use bookmarkable links when you refer to something that would eventually
require from the recipient to search for in another platform.

This has two benefits:

• Save time
• Eliminate ambiguous references

Examples

Before

Dear Phoebe,

I didn't understand the process described on the issue about the logging 
bug. Irida's comment was not very clear either. Can you please help me?

Thanks,
Lazarus

After

Dear Phoebe,

I didn't understand the process described on the issue about the logging 
bug (Redmine #453). This comment from Irida was not very clear either. Can you 
please help me?

Thanks,
Lazarus

Structure long messages

Long messages are in general not very effective and parts of them are
prone to be ignored.

When I have to compose such a message I try to categorize the text in
contextual sections and then structure them using headers and
paragraphs allowing readers to navigate to them at a glance.

Examples

Before

Dear team,

Last week we had a problem with the logs in the production environment. I 
am talking about the Redmine issue #453. We noticed a huge increase in 
the log messages blabla leading to delayed responses because blah blah 
blah. At some point the server run out of disk and everything fell apart 
blah blah blah. Administrators backed up the logs and removed them from 
the server to blah blah blah. We started investigating what is going on 
immediately and after two days we managed to reproduce the error in the 
staging environment as well. The problem was the usage of an external 
library that had a bug which blah blah blah. We removed the library and 
the bug was no longer reproducable in the staging environment. The buggy 
library was blah blah blah. We released the fix yesterday and everything 
seems to be back to normal. We also added some scripts that will notify us 
immediately if such conditions start to emerge.

Thank you for your time,
Lazarus

After

Dear team,

Background
Last week we had a problem with the logs in the production environment. We
 noticed a huge increase in the log messages blabla.

Consequences
The increase led to delayed responses because blah blah blah. At some 
point the server run out of disk and everything fell apart blah blah blah.

Cause of the problem
We started investigating what is going on immediately and after two days 
we managed to reproduce the error in the staging environment as well.
The problem was the usage of an external library that had a bug which blah 
blah blah. The buggy library was blah blah blah.

Actions taken

1. Administrators backed up the logs and removed them 
from the server to blah blah blah.
2. We removed the library and the bug was no longer 
reproducible in the staging environment.
3. We released the fix yesterday, June 26th, 2019.
4. We also added some scripts that will notify us on time 
if such conditions start to emerge.

Current status
The server is up and running, everything seems to be back to 
normal.

More info
Related Redmine issue #453
External library - Official bug report

Thank you for your time,
Lazarus

Be specific on what you request from whom

I have seen many many many emails for which:

• the sender wanted something by someone
• the recipients
  • didn't think they were the ones to provide it
  • understood something else than what the sender asked for

I try to be very specific and provide details (when possible) on what I
need and when there's more than one recipients I refer to each one
explicitly using @.

Examples

Before

Dear all,

I have pushed a commit that possibly fixes the bug with the logging in 
staging. I won't be here tomorrow so can you review and release if ok?

Bye.

After

Hey,

I have pushed a commit that 
possibly fixes the bug (Redmine #453) 
with the logging in staging.

Since I won't be here tomorrow, June 27th, can you 
please:

@captain: review the commit
@qa: run the suite to validate 
the fix
@devs: proceed with the production release 
on June 28th given the green light by the QA team?

Sorry for the inconvenience,
Lazarus

Thank you,

Lazarus

Post Scriptum

This post was originally published on my blog.

Find attached a photo of my cats.

Comments

[Fred Heath]

Some very helpful tips here. May I add another one I learned the hard way after working in remote teams: unless you're absolutely, positively sure that your email will be read only by people in your timezone, use UTC times, e.g "let's chat at 13:00 UTC"

[Lazarus Lazaridis]

That is correct, Thank you!

[Michael Tharrington]

Really good article, but more cats next time please! 😸

[Lazarus Lazaridis]

Thanks! More cats? That will not be a problem at all :D

[Michiel Hendriks]

When I'm writing an email that is longer than a paragraph I generally start with an executive summary. Because most people want to be executives and don't read the email. So, important stuff first. After that comes the detailed information and background.

Then when people respond I can simply refer to my original email, which they didn't read fully, but does contain the answer to their question.

[Josh Ransley]

Some good tips here. Some may seem over the top for an email, but they mean you get the point across with fewer (or no) follow up emails.

I often include full dates and 24-hour times in emails, just so it's clear what I'm discussing, with no ambiguity.

The examples are very helpful too, they make it much easier to imagine how to use your tips. Nice.

[Lazarus Lazaridis]

Thank you Josh!

[Mirosław Farajewicz]

Superb article. Bad vs Good examples are always easy to understand.

For non-native English speakers I can also recommend two tools I usually use when composing mail:

• Grammarly is well known Chrome extension, and allows us to quickly solve many issues with our text
• hemingwayapp.com/ - this I use only for longer text - similar to Grammarly but focuses more on readability not grammar

Also, the rules mentioned in this article are pretty useful: medium.com/swlh/write-to-express-n...

[Lazarus Lazaridis]

Thank you for the feedback!

[Patrick Tingen]

I wasn't planning on 'liking' your post, but then I saw your cats...

No, just kidding. Very good and readable post. I really love the fact that you added examples. Posts on better mailing behavior often lack good examples, thanks!

[Lazarus Lazaridis]

Haha, thank you very much Patrick!

[TuWang]

Another point I recently realize: avoid sharing too much unnecessary details(like my inner thoughts or concerns regarding the subject). That becomes noises to the audience.

Great post ;)

[Lazarus Lazaridis]

Good point, thanks for your feedback!

[Daniel Barwikowski]

Good tips. I will try to follow them in my emails. Will see the outcome :)

[Lazarus Lazaridis]

Thank you Daniel, I hope they help :)

[Ian Wijma]

This is super helpful with communication in general. Thanks for this post!

[Lazarus Lazaridis]

Thank you!