How to write better emails

Tips for composing effective emails avoiding misunderstandings with examples from the software development world.
Αυτό το άρθρο είναι διαθέσιμο και στα ελληνικά.
I just released stup, a tool for easily keeping organized daily notes in the terminal. You can find it on GitHub here.

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

Find attached a photo of my cats.

Meow have your attention please?

Comments and feedback
For feedback, comments, typos etc. please use this issue.
Thanks for visiting!