Recently I covered the topic of Communication as discussed in The Pragmatic Programmer.

The book also has a single page dedicated specifically to online communication, and I thought it would be great to discuss it here too. Our world revolves heavily around online communication - blogs, instant messages, and, most of all: email.

It stands to reason that email is an important enough medium to pay some attention to how we use it. Your most valuable tool here is proof-reading: don't just tappy-tappy-I-have-an-email-hit-send -- we all make mistakes. Take the time to read over your email. You wouldn't want to give a presentation without checking your slides, or submit an article without reading it first. Your email should be the same.

How not to write an email:

Proof-reading

Look for any of the following before hitting SEND:

Spelling, grammar and auto-correct mishaps

Even if you have a spell-checker enabled, there are some grate miss steaks the chequer can knot ketch. Also, a lot of emails these days are sent from mobile devices -- phones and tablets with software keyboards which try to do their best with correcting mistakes, but often just make things worse!

A quick read-through may highlight some of these, though it's also possible to miss these mistakes on a proof-read, so I suggest that, for really important emails, you call on a friend to help. I also use this method to check tone on an email, especially when I'm annoyed about a situation: I don't want my annoyance to come through in the mail and hamper a solution to the problem.

Simple and clear formatting

Try to keep your writing as simple as possible:

• bullet lists help
• carve up long paragraphs
  • try to keep one point per paragraph
  • DRY is good for emails too!
• headings for areas in longer messages

Keep it short

Time is one of only two resources we have. Respect the time of others. You may spend an extra 5 minutes making your email succinct, and that may save countless minutes on having to re-illustrate your point, as well as the time it saves on the initial read for each of your recipients.

You can't expect others to respect your time if you won't respect theirs.

Dealing with necessarily long emails

I have found that sometimes I have to write a longer mail to get all of the technical details in there, but often people just stop reading after a certain point.

I've found that the following helps a lot: try adding a Summary section at the top of the mail, with a Details section afterwards. I used to label the summary TL;DR, but apparently there are plenty of people who don't know what that means😑 so now I normally stick to "Summary" and "Details". For a more informal email, I'll use "The short story" and "The long story".

I also like to make it clear, when appropriate, if reading the details is optional, ie if the summary clarifies well enough for the manager and the details provide the extra information for the techies, then I like to add something like "If you're interested in the details, then..."

Quoting

Keep quoting of others to a minimum: only quote where necessary, ie when responding to a particular concern of someone else on the email chain.

Also find out whether the generally-accepted practice for the list or audience you're dealing with is to top- or bottom- post. I prefer top-posting, since it means I can open a mail and read the latest information at the top. But some lists (like the gentoo lists) prefer bottom-posting, so everyone is used to that style and it would benefit you to stick to it

For those unsure: top-posting means that when you reply to an email, your new information goes at the top of the mail; where bottom-posting means you add to the bottom of the mail. Bottom-posting is normally favored in more venerable communities where top-posting is more the norm applied by modern email clients.

Attribute original authors

If you have to quote someone else, whether on the email chain or from another document, attribute them. One of the poorest images people can have of you is that you steal or randomly copy other people's work. Even if you didn't intend to pass off that information as your own, it's good to be clear about it.

Side-note: the same goes for cut-n-paste code. If you find a solution on StackOverflow, you must attribute the original author. It's actually part of their terms of service now!

If you wouldn't say it to their face, keep it out of the email

Try to keep it civil. If you wouldn't say what you're about to write to the face of a person on the email, or a person who is likely to find out about or read the email, then find a different way to express yourself. Don't troll or flame. I promise that doing so will come back to bite you in the long run.

If you're frustrated or annoyed with respect to the subject being discussed in the email, or even if you're annoyed with (or just can't stand) someone on the email chain, try to keep that emotion out of the communication. Leaving it in makes you look bad and certainly won't help you to achieve whatever you're setting out to do. If you're unsure, get someone else to read your mail and help you with the tone.

Check the recipients

Always double-check that the people in the recipients lists are the correct audience for your email.

Does your reply really have to be "reply all"? Countless times I've seen (at a larger company) a company-wide email asking, for example, who needs a new pen, and a few people replying back to the entire company that they'd really like one, and placing orders for specific colors!

You shouldn't be talking smack about the boss in an email anyway (see above), but it's especially stupid if the boss is part of the email chain. By the same token, it might be acceptable to vent frustrations over a certain vendor internally, but I'm sure that sending those kinds of mails to the vendor won't help your case!

Use a thesaurus

Even whilst writing this post, I've consulted thesaurus.com for alternative words which better communicate the points I want to make. If you find that you're using the same word over and over, look for an alternative to keep your readers reading.

Wrapping up

Email and media posts last forever. There have been plenty of corporations, politicians and celebrities who have found this out the hard way!

Put the same effort into your emails that you would into formal documents. Remind yourself that, the moment you hit SEND, the words you've expressed are essentially linked with your name for the rest of your life. Don't compromise your future by being hasty or shoddy in the present.