How to write an effective email as a software engineer

Note: this article was originally published on LinkedIN

You may think most software engineers know how to write effective email but you'd be wrong. Email was invented by software engineers, but it is still a difficult tool to use to communicate technical content.

So what can software engineers do to write better email?

Provide one clear takeaway

The first rule of email is that each email should have one clear takeaway.

If this is the only takeaway you get from this article, then I've done a great job. (See what I did there?)

Before you sit down to write an email, think of a simple, clear, and short sentence that sums up the email. Does the reader need to take an action? Is there a vital piece of information that you need the reader to know? What is the one thing they need to take away when they get up and walk away from the screen? I learned this tip from a Harvard Business School book on business communication.

If you can't summarize in a single clear sentence what you want the reader to know or do as a result of reading the email, grab some tea or coffee while you think about it.

Put the takeaway in the subject line

When you have that one clear sentence straight in your head, come back and write it down in the subject line.

(Skip the recipient lines (to, cc, and bcc) at the top for now. You can enter recipients later after you're sure you have written an effective email.)

Now improve your subject. Remember that it will appear in the middle of a list of dozens of others, so you should make it great. With a great subject line, you can rest assured that if the recipient reads nothing else, they still get the message.

Consider that many people now read email on smartphones and tablets. This usually truncates most subject lines after four to seven words.

Subject line examples

Here are some example subject lines for technical email:

• Please update: InternalLib 4.0 is now available
• Last chance: Submit feedback on draft Go coding guidelines
• Signup now if you want to teach a March brownbag session
• New coffee blends now available in the breakroom

Aim for five sentences or less

What about the body? Is it a place to make further points than the one made in the subject line?

No.

The body of the email is for a few additional details about the subject only. Keep in mind that the reader probably has 40 other emails to read, besides meetings to attend and sprint commitments to deliver. They have made their valuable attention available to read your email, so make it count.

As a general rule of thumb, try to limit the body to less than five sentences. Five sentences is not an arbitrary number. There is actually a movement online to reduce email length. Visit http://five.sentenc.es/ to find out more.

An email's body should spur the reader to action. It should not cover other points outside the subject. If you need to convey another, separate message—even if it's related—send a separate email or link to a document after conveying the more important primary point.

This can be counter-intuitive. Once you have made your point in the subject line, you may feel that the other party should have as much context as possible. Resist this urge. If you absolutely feel that more context is necessary, attach a document or leave a link to a web page with that information instead.

But how do you choose what context someone needs immediately versus what can be linked? Especially considering that attached or linked content may never be opened by a busy recipient?

Providing context

In the case of an action-oriented email, consider if the recipient will need to make a decision in order to choose the right action, and give them the context they need to make that decision. For example:

From: Hamilton, Margaret <mhamilton@example.org>
Date: Monday, January 27, 2022 at 11:53 AM
To: Lovelace, Ada <alovelace@example.org>, Hopper, Grace <ghopper@example.org>
Subject: ACTION: Update log4j in your applications immediately

A critical vulnerability in the log4j library has been discovered. Please update to version 2.15.0 immediately.

- Link: How to find out if your application uses log4j
- Link: Log4Shell FAQ
- Link: Security team support page

Thanks,

Margaret

Here, the action is clearly expressed in the subject. The first two lines of the email provide context for that action including why its necessary and what version to use in the update. The following three bullets are all links to further context some recipients may need in order to perform the action.

The non-email option

If you are struggling with communicating a single, clear point in an email, then maybe you need an alternate form of communication:

• A meeting
• A Gitter room or Slack channel
• A pull request
• A shared document with commenting turned on
• A JIRA story

Use your imagination and your available resources.

Your email may turn into a short invitation to comment on a document, review a PR, or attend a meeting instead.

Replies

If you haven't seen it, a great guideline for replies is the following, from www.five.sentenc.es:

Treat all email responses like SMS text messages, using a set number of letters per response. Since it’s too hard to count letters, we count sentences instead.

www.five.sentenc.es is a personal policy that all email responses regardless of recipient or subject will be five sentences or less. It’s that simple.

Email Debates

It often happens that programmers engage in email debates. Because of the discussion list culture among developers, there is a tendency for even short emails to turn into long email chains. Unless you actually are on a mailing list whose purpose is to have longer discussions, this is a faux pas.

It can be hard for any developer to resist a debate, particularly when someone has said something incorrect, or something inflammatory, about their favorite language or framework. But this is the chance to go with the better, non-email option.

Here is an example email for those times when the debate is too big for email.

From: Lovelace, Ada <alovelace@example.org>
Date: Monday, January 24, 2022 at 8:53 AM
To: Hamilton, Margaret <mhamilton@example.org>, 
Hopper, Grace <ghopper@example.org>
Subject: Re: Proposed HTTP client library 

Hi everyone,

Can we move this discussion to the Gitter room instead? 
It seems clear that we need to incorporate these points into 
the decision and the Gitter room is where we're getting 
everyone's feedback on it. Besides, a number of people who 
should be involved aren't on this email thread.

Thanks,

Ada

Furthermore, this is another reason not to include more than a single point in your email. If your email covers multiple, separate points, you will end up with a reply thread that is going off in all directions. And that means no one is getting any of it.

Don't send it yet

Done? Great! Now revise. Maybe even get a second pair of eyes on it. You should spend as much time revising it as you spent writing it, maybe even more. You only have one chance to get it right!

Mark Twain famously remarked, "...if I had more time, I would have written a shorter letter." Long emails actually communicate less than short emails.

Send it!

You've taken into account all of the above advice. You feel your email is perfect. It's going to get the right message across and do so effectively. Add your recipients, click send, and sit back knowing that you cut through the noise.