Αυτό το άρθρο είναι διαθέσιμο και στα ελληνικά.
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
Find attached a photo of my cats.
Comments and feedback
For feedback, comments, typos etc. please use this issue.
Thanks for visiting!
(