Software development is much more than just coding. Writing good code is a starting point, but along with that a software developer must also be an effective communicator. Among all the modes of communication we have at our disposal, email continues to be the most widely used medium. Especially since it's asynchronous nature makes it extremely effective for global teams. Writing effective emails is not formally taught to programmers, and yet emails are the lifeline of a development team. We use emails to communicate bugs, to discuss feature requests, development plans, brainstorming and much more. Clear, well written email communication enhances a team's productivity, while badly written emails become the proverbial clog in the wheel.

 

You don't have to be an English major to compose good emails. Writing effective emails is mostly a matter of clear communication, having respect for other people and their time, and a lot of common sense. Taking care of a few key points will go a long way in increasing your email prowess.

 

Email communication covers a wide range of contexts. We exchange emails with upper management, managers, customers or third parties outside the company, and our team members. In this article I'll specifically focus on on giving pointers for technical (project related) emails we send to team members.

 

 

Every email should have a very clear subject line which describes the purpose of the email briefly. Along with informing your audience what you want to communicate, they also help in searching for past discussion threads. 

 

I'll start with giving examples of bad subject lines. The following subject lines or their lookalikes should never be used. Not only  do they look unprofessional, but they also make it impossible to search for past emails in any meaningful way:

 

Notice how none of them describe the email's purpose. If I get a message with any of these subjects, I might think it's just casual communication and may not read it till later in the day. If the sender meant to convey something important in the email, it might not be read as early as it should. Conversely, it's also a good idea to refrain from using SOS kind of lines, such as:

 

 

Sometimes, in exceptional cases it's alright to have a word in the line which indicates urgency (although urgency is better signaled by using a higher priority for the email), do be mindful that what seems urgent to us in the stress of the moment may not indeed be that urgent for the team. Misusing alarming subject lines is one of the quickest ways to make people not take your emails seriously in the future. 

 

Let's shift gears from what-not-to-do to what-to-do. If your email refers to a bug then include the bug number along with a short description of why you are writing the email. Something like this would be a fairly descriptive subject:

 

 

Here's an example of your subject line might look, if you are reporting a feature that's not working properly.

 

 

 

 

Nowadays, as developers, we are inundated with tons of communication, especially emails. This deluge of information along with the short attention span we seem to have developed (perhaps in response to this deluge) has induced a certain behavior pattern where many people reply to shorter messages immediately, while putting off longer messages for later. We can't do much to change other people's habits, but we can be careful with the way we draft messages to ensure that our emails get the attention they deserve.

 

Short and clear messages have a far better chance of being read and replied to immediately as compared to those that are long, convoluted, and distorted. A message is short when it does not contain extra information which detracts from the main point. However, the main point itself should never be compromised to reduce the length of the message. Along with the message itself being short, it's sentences should also be short and clear and paragraphs short and well defined.

 

I have often seen (and even written) emails which have very long winded sentences that are almost a paragraph long. Oftentimes, we construct such sentences when we directly transcribe our thoughts into words. It's important to understand that thoughts and words belong to different mediums and must be represented as such. If you have difficulty formatting shorter sentences from your thoughts, then try to represent the thoughts first as bullet points followed by constructing sentences from the bullet points. 

 

It's equally important to construct coherent paragraphs. Interestingly the rules for good paragraphs is surprisingly similar to a certain programming principle: The Single Responsibility Principle. Just as every method in a class is supposed to have one clear responsibility, every paragraph or section in an email should convey one and only one aspect of what you are trying to communicate. 

 

Further, the email as a whole, should communicate just one issue. It's always a good idea to create different emails for different issues, even if it results in a lot of small messages. This makes it easier for people to reply and track the discussion.

 

 

This is especially true when you are trying to communicate something that happening on the screen. So instead of simply saying that the right border of the dialog box is 20 pixels thick, the top and bottom borders are missing, and the message is missing as well, also send an image which shows exactly what you mean.

 

 

 

 

 

I ran into an interesting bug with a third party library a few years back. The bug was interesting because it happened only when a series of actions were performed in a particular sequence and with specific input values. I send an email to the developers explaining how to reproduce the bug, but for some reason they had a hard time with it because the sequence of steps was very long and complex. I could have send them images of my screen as I performed each action, but I was skeptical about how effective it would be to send 40 - 50 images to describe the whole process. A colleague made an excellent suggestion. She suggested that I send them a video of my screen as I performed the actions. Bingo! That did it. They watched the 5 minute and understood exactly what I meant. 

 

If you do decide to send videos, please don't attach them to the email. It's better to upload them to a shared repository and email a link to the video with an explanation.

 

 

I hope this article has helps you draft better email messages and become well rounded developer and communicator. For now I have limited the context to technical emails send to team members, but I will also discuss other contexts and aspects of good email communication in future blog posts. Stay tuned...