Writing emails: objectivity without rudeness
How to signal good intentions in short emails
The problem with email is that it makes harder to correctly signal your intentions. When you are communicating, intentions always count. But email, when compared to other channels, has limitations that get in the way of properly transmitting intent: it is written, it is asynchronous, it is a dialogue, it is ubiquitous.
It is written, so, unlike face-to-face, video or audio, you miss all the cues that humanity optimized to signal the kind of relationship you want to establish. Things like facial expressions, body posture, and tone of voice. It is asynchronous, so, unlike instant messaging, it is uncertain how, when and if you will receive feedback on your message. It is a dialogue, so, unlike blog posts, it is personal and intentions are pointed directly at the reader - even if it is a one-to-many email. It is ubiquitous, so, unlike intra-company communication channels, there is no implied common standards and practices.
When writing an email, you have to pay so much attention to how the reader will read it, that you may neglect what they read. It is the risk of caring so much with signaling intentions that the content is lost in verbosity and amenities. Software developers tend to err on the side of short, blunt, curt emails. So I will try to help you write emails that do not seem rude while avoiding fake politeness, passive-aggressiveness or just adding noise.
As with all written communication, you should also follow the basic flow (better presented here): before you write it, think about the message; while writing, think about the person; after writing, rewrite it. But with email, there is an extra step: check your emotions. To not sound rude, you have to not want to be rude.
Seriously. The impression I get when I read Linus Torvalds famous rants is that he consciously wants to be rude, that’s not a lack of written communication skills. But it is also possible to want to be rude without even noticing it yourself. It happens when you are writing in a bad mood. So check your emotions: if you are angry, annoyed, or impatient, take extra care to control how much of it, if any, you want to be reflected in your text.
There are some good practices to avoid unintended rudeness. I will use examples to more practically demonstrate what I mean. I list some tips with bad and good samples of text applying the advice and a cautionary example showing that is also possible to go too far with any of this tips.
Tips for nice emails
Tip #1: When it is a suggestion, make it explicit by adding "What do you think?" and other uncertainty cues.
Rude-sounding example:
Break this method into two and isolate that conditional statement into a constant.
Nicer example:
You should break this method into two and isolate that conditional statement into a constant. What do you think?
Going too far: When it is not a suggestion, don't pretend it is.
Better risk sounding harsh than be unmasked pretending fake intentions disguised as politeness. You will either lose credibility of your intentions or sound passive-aggressive.
Dishonest example:
You should wait for at least one other developer to approve your Pull Request before merging it, as it is the rule of our company. What do you think?
If it is the agreed rule, it is the rule, not a suggestion.
Tip #2: When it is an opinion, make it explicit by adding "I think..." and other uncertainty cues.
Rude-sounding example:
This is not good practice on large-scale codebases.
Don't pretend is a fact either.
Rude-sounding and dishonest example:
This is a notorious anti-pattern for large-scale codebases.
This is dishonest only if it is not actually a notorious anti-pattern of course.
Nicer example:
I think this is not a good practice (or at least a point of attention) on large-scale codebases because of how it negatively affects performance.
Going too far: When it is not an opinion, don't pretend it is. If you know something for certain, make it clear.
Dishonest example:
I think this is not a good practice because it might affect performance
If you know it affects performance, it does affect, not might affect.
Tip #3: Criticism must come with support
Rude-sounding example:
Your tests are not covering relevant use cases and I have the impression you are confusing the roles of unit and integration tests.
Nicer example:
Your tests are not covering relevant use cases and I have the impression you are confusing the roles of unit and integration tests. I can help you with that. Check this <linked article> for some clarifications and let me know if you want a deeper explanation, so we can schedule it this week.
Going too far: Don't obfuscate the critic being overprotective or too uncertain.
Confusing example:
I know you are just beginning to write tests for this codebase - and it is a lot of spaghetty legacy mess, right? - but I am afraid your use cases are not covering everything they should, although the ones you created are very well written. There might be some confusion on your part about the roles of each type of test, but I am not so sure about that. It depends on what you were trying to accomplish.
Tip #4: Use exclamation points and emoticons to set the tone right
Rude-sounding example:
I saw you merged the Pull Request and it is great. It's ok you already merged it after Liz approval, but remember to tag all the reviewers on slack. You forgot to tag me and I hadn't the chance to review it.
Nicer example:
I saw you merged the Pull Request and it is great! It's ok you already merged it after Liz approval, but remember to tag all the reviewers on slack. You forgot to tag me and I hadn't the chance to review it :(
Going too far: Don't use it too much.
Awkward example:
I saw you merged the Pull Request and it is great!!!! ♥‿♥ It's ok you already merged it after Liz approval \ (•◡•) /, but remember to tag all the reviewers on slack ಠ_ಠ.
You forgot to tag me (ง'̀-'́)ง and I hadn't the chance to review it!!!!!11 ¯\_(ツ)_/¯
Going too far 2: Don't include jokes just to lighten the mood.
Humor works better in face-to-face, synchronous, and group communication. Also, humor is for naturals - maybe someone out there is writing a "humor for developers" newsletter, but it is hard to pull-off good comedy on professional communication without sounding just ridicule.
Out of place example:
I saw you merged the Pull Request and it is great. It's ok you already merged it after Liz approval, but remember to tag all the reviewers on slack. You forgot to tag me and I hadn't the chance to review it. Remember that time you "forgot" to invite Mike to a beer with the team?? lol I hope it is not for the same reasons here lol"
Tip #5: Don't blame the reader by using "per my last email" or "as I mentioned earlier"
Rude-sounding example:
As per my last email, the deploy will only happen after our Product Manager checks with our partner if their API is ready. And she has not done that yet.
Nicer example:
Just give cue words (e.g. “still”) that you mentioned it before, but don’t make it explicit. Explicitness, in this case, is used to suggest that the miscommunication is the reader’s fault - and that is not a useful practice to have, even if it is true.
We are still waiting for our Product Manager to check with our partner if their API is ready. I will ask her if there is an expected time for that and come back to you.
Going too far: Don't just repeat the word-by-word information without any clue that it was already mentioned before.
The reader might have the impression that you are taking them for fools.
Dismissive example:
The deploy will happen after our Product Manager checks with our partner if their API is ready.
Tip #6: Add a descriptive subject line
Rude-sounding email subject:
<no subject>
Nicer subject:
Team repository access
Going too far: Don't be demanding in the subject line.
Even if the message is to ask for something quite straightforward, asking it in the subject line will look angry and bossy.
Aggressive subject:
Give me access to team's repository
Tip #7: Always include a greeting and a sign-off
Rude-sounding example:
Can you give me access to the team's repository?
Nicer example:
Hey Tim,
Can you give me access to the team's repository?
Thanks,
Rod
Going too far: Don't keep using it in long threads with several back-and-forth emails with the same people.
It will look like you are artificially reinforcing some formality and distance, thus some power hierarchy. Once it became a de facto instant messaging, you should behave like such.
Distanced example:
Hey Tim,
Ok, sure! I'll ask her to do it for Peter too.
Cheers,
RodHey Tim,
Oh, I didn't know I had to be added to the organization's Github first. I will ask Stephanie to do that first then.
Cheers,
RodHey Tim,
Yes, it can be read-only for now, as I am just studying the codebase.
Cheers,
RodHey Tim,
Can you give me access to the team's repository, please?
Thanks,
Rod
Going too far 2: Don't fake intimacy or be over the top in friendliness.
Pushy example:
Hello my dearest Tim,
Hope your week’s off to a great start! How was your weekend? Are the wife and kids well?
Can you give me access to the team's repository, please?
The most sincere and warmest of the regards,
Rod
Tip #8: Always say please and thank you
Rude-sounding example:
Give me access to the team's repository.
Nicer example:
Hey Tim,
Can you give me access to the team's repository, please?
Thanks,
Rod
Going too far: Be careful to not give the impression you are saying it sarcastically
Possibly sarcastic example:
If it is hard to identify sarcasm in written form, imagine creating an example that conveys sarcasm in a hypothetical scenario. So, please help me here and make an effort reading this aloud adding sarcasm to your tone of voice.
Hey, Tim. Could you please give me access to the team's repository. Thank you very much.
I tried to focus on small practical tips for everyday use. One thing that I want to do recurrently is to address the real situations you face in your day-to-day. So if you are concerned with a particular text and how to write it better, please email me and I will give advice for your specific situation. Better if you let me use your sample of text for a public post (with any identifying information redacted, of course).
Other writing tips for developers
This is the second email (first one here) of my newsletter with writing tips for software developers. If you want to get a weekly boost to your written skills and become a more effective software developer, please subscribe.
