Context
What the readers need to know before they can understand you
An often neglected aspect of effective communication is context. Maybe because "context" is hard to define and put in concrete terms. You can think of it as everything the reader needs to know in order to comprehend your core message. Sometimes you give context by sharing something new to the reader, providing an update to their knowledge. Sometimes you are just specifying what you are talking about so they can remember and put their minds in the correct place while reading you.
You also have to consider that lots of things provide context, not just your text. When reading a commit message, the setting comes from various sources. The code itself contains a lot of meaning: which project, which file, which lines are being edited gives a lot of information. Who is committing is also part of the context. So a commit message needs very few words to provide context, and you can often jump right to the core message of informing what change is being proposed.
On emails, on the other hand, there is minimal inherent context. The only source on context information is who is sending the email. This can provide valuable information though. If it is from someone working with you on a specific project, you can assume the message is about that project. If it is from someone from the Human Resources department, you can assume it is about your employment relationship, not code. People have the same expectations of you, so if you are sending an email about a topic that you normally do not deal with that person, make some extra effort to make it clear.
Aside from coming from you, think about what information you need to include in your email before the person is ready to understand the message you want to transmit. It may be just a well-thought subject line, or it may need a whole introductory paragraph. Just include the minimal information required to bring the reader to the same page as you. Not more.
An example
Imagine you are coding a new feature that adds a Help modal at the customer's interface. It will include the Customer Support email address, but you want to double check which email to use because you heard the Customer Support team has a new structure and is creating separate email accounts for distinct purposes. You want to find out who is the person on the Customer Support team that can confirm that to you.
Sending to another developer on the same team
subject: help modal
Hey Lisa,
Do you happen to know who on the CS team can confirm if I have the right email address to add to the help modal?
Thanks,
Sending to your Product Manager
subject: help modal
Hey Stef,
Regarding the "Help" modal I am working now, I want to double check the email I will include on it.
Do you happen to know who on the CS team can confirm if I have the right email address to add to the help modal?
Thanks,
Sending to another developer on another team
subject: need help to contact the CS team
Hey Jerry,
I am working on a new "Help" modal that will be added to the customer interface when they click on "Support". I want to double check some information before committing it.
I know the CS team is using separate email accounts for support now.
Do you happen to know who on the CS team can confirm if I have the right email address to add to the help modal?
Thanks,
Sending to someone on the CS team
subject: need some clarification about Support emails
Hello Joe,
My name is L, I am the software developer creating the new "Help" modal that will appear to the customer when they click on "Support", on the main page of our site.
Before finishing it, I just want to double check which email should I include in this modal. Because I know that you are using separate email accounts for support now, right?
Do you happen to know who on the CS team can confirm if I have the right email address to add to the help modal?
Thanks,
The rule of thumb here is that the more distant you are from a person in your day-to-day work, the more information you need to add to provide context.
