This chapter is a comprehensive guide to professional engineering email. We’ll cover organizing information, but we’ll also discuss subjects like selecting an audience, tuning your level of formality, formatting, how to show respect, and small-but-nonobvious details like addressing and signing. First: motivation.
You’re going to write a lot of email as a software engineer, and if you’re lucky, you’ll read only ten times as much; if you’re really lucky, some of it won’t be terrible. You’ll read every variety of bad email: emails that are way too long, emails packed with useless detail, confusing emails without enough context, off-topic replies, and emails that make enemies for no good reason. Above all, you’ll read irrelevant emails that should never have been sent.
I’m a slow emailer, endlessly revising and agonizing over every word, preoccupied with all the above traps; I’ve often spent a whole morning on a single delicate message. Still, I’ve found that investing in effective email pays for itself many times over in project results and reputation—results because projects go better when your collaborators know what’s going on and what you need from them, and reputation because engineers, focused on code rather than humans, find good email a mystical skill.
The Art of Sending and Not Sending Email
Email is still technical writing (Chapter 12), and my best advice is therefore to write briefly and clearly. If all you do is follow the advice of that chapter, you’ll be above average: emphasize your conclusions, edit for brevity and precision, focus on what your readers care about, and remember what they know and don’t. That said, email demands many small decisions irrelevant to a stand-alone technical document.
Structure
Hi SRE Team (cc Dhivya, Jeff from Storage), tl;dr Centralized DB tracing rolls out tomorrow; view your instance’s logs at dbtracing.ourcompany.com. In an emergency, disable tracing in the config flag system at config.ourcompany.com/tracingprop. Starting tomorrow, we’ll be rolling out centralized tracing for our MySQL instances. Logs are aggregated in Elasticsearch and can be viewed per-instance on dbtracing.ourcompany.com. The log extraction is based on Filebeat and is expected to be minimally invasive, but in an emergency, it can be disabled per-instance by setting enabled to “false” at config.ourcompany.com/tracingprop. If you have an urgent need to increase verbosity, you can update the log level there as well. We’ll send an update when this rollout is complete. Feedback and questions are welcome and appreciated. Thanks to Dhivya and Jeff for their hard work to make this possible! Cheers, DH | Salutation: whom you’re writing, possibly calling out the people you’re directly addressing and those you’re merely keeping in the loop separately. Followed by a comma Optional tl;dr: Body Section 1 of N: most important points if possible, should frame everything else Body section 2 of N: more detail; striving to cover only one subject per section, in this case operational concerns Optional closing: an opportunity to prepare for future communication, reiterate important points, show respect, and give credit Signature: purely a formality in the email age but obligatory to avoid undue informality |
Salutations
Most business emails today begin with
Hi <person or group>,
That is, “Hi,” some identifier for the addressee, and a comma. Historically, we often used colons to terminate salutations in business emails, but this is fading—use commas. The first character is always capitalized, and names are always capitalized; groups may or may not be.
Hi Apoorva,
Hi Amaliya and Jeremy,
Hi migration team, // Looks a bit informal, but can be acceptable
Hi folks,
When addressing a small- to medium-sized group, the preferred form is “Hi folks.”1 “Guys,” previously used in the gender-neutral plural, is now widely considered as sexist and should be avoided entirely in business contexts. For larger groups, you can use “Hi everyone” or “Hi all.” The most complex form you’ll need to use on a regular basis is when addressing one group but CCing another—for example, if you mail the web team but want to inform the back-end team. In that case, you should make it clear whom you’re CCing in parenthesis; this lets others replying adjust their replies for the audience.
Hi web folks (cc Chen and Mike),
For very short emails to close collaborators, you may omit the salutation, but I almost always include it to avoid sounding curt.
Finally, when in doubt, mirror what’s already been used on a thread!
Signatures
You have four options for signing an email:
Just your name: This is fairly informal, appropriate for fast, efficient conversations between peers. I wouldn’t address a superior this way, and I find it a bit short for strangers. This might be the right closing for an email that also doesn’t need a salutation.
Sounds great to me!DH
Cheers: This is a friendly, cheerful signature appropriate to an email between peers who might not be on such familiar terms that you want to end without a signature at all. It’s also appropriate to large lists with a variety of people on them.
Hi everyone,
This plan sounds good to me! Let’s run with it.
Cheers,
DH
Thanks: This is just slightly more formal than “cheers” but can be used in more or less the same circumstances (especially when you’re thanking people!). It’s an appropriate signature for large lists within your company, superiors, senior colleagues, and colleagues within your company you don’t know well.
Regards or best: These are the most formal, appropriate to business interactions between people from different companies, especially if you haven’t worked together extensively. We generally use the most formality when going outside of our own company or across major branches of a company; they’ll sound stilted in normal internal mail but are more or less the only option for initial interactions across firms.
Hi Maria,
Sounds good to me! I’ll meet you and your team in our lobby on Tuesday at 11AM.
Best,
Dan // Note use of my name, rather than my initials/nickname
The Importance of TL;DR
tl;dr Many readers don’t have time to read every word of your email, especially executives. Start your emails with an ultra-brief summary in boldface.
tl;dr means “Too Long, Didn’t Read”—a snarky response to a long Internet post. In a professional context, it refers to an ultra-brief summary of an email or document, placed upfront for people who want to know what’s up but don’t have the time or appetite for every word. Some emails are only two sentences or go to a single recipient who does care about every word. In that case, skip a tl;dr. Most emails, though, go to larger audiences, and lots of those readers are going to be short on time—most importantly, that includes executives, whose calendars are horror movies and who almost never need to know the details. Almost any email with complex content and a large audience, especially technical announcements, should offer those readers an ultra-condensed summary, set in bold and explicitly labeled tl;dr.
Replying On Topic
Every week I see engineers and managers reply embarrassingly off-topic to clear questions. This may sound obvious, but irrelevant responses come off poorly and, more importantly, are frustrating to question askers (“now I need to reply to that whole thread and ask the same question again!”). Read, read, and read again, model the mind of your correspondent, ask yourself what exactly is this person asking, ask for clarification 1:1 if you need it, and then, finally, reply magnificently on topic.
Large Mailing Lists
Large mailing lists are high-risk, low-reward. It’s easy to embarrass yourself with a stupid question (yes, they exist) or the wrong tone but rare to impress or sway people enough to justify that risk; therefore, I almost never send a message to a large list, and I advise you to do the same. You can usually get the same rewards at a fraction of the risk by talking to someone 1:1 or tracking down a smaller mailing list.
That said, there are (rare) times to hit reply-all to a few hundred people—say, someone asks for help with a problem that many people have, and you’re (for some reason) the only one who knows the answer. When you do reply-all, it should be with super-premium content, material of great technical interest and utility to the audience, presented with a positive attitude and respect, polished to a mirror shine of good spelling, structure, and grammar—we put only our best foot forward.
Once in a great, great while—once in five years or even less often—tremendous conviction may shove you into making a controversial point (also with a positive attitude, respect, and humility). I have literally never felt the need, and if you do, you’re probably wrong. Walk away and think about it.
Whatever the complexities of that decision, let me offer one iron rule—never, ever, ever reply to a large list in anger or with disrespect; you’re hurting your own reputation and dignity far more than you’re helping your cause or gratifying yourself, and you just might find a way to get yourself fired (I’ve seen it happen). There are no exceptions.
Etiquette, Formality, and Polish
- 1.
Never, ever show anger or disparage another person over email, even 1:1 to someone you trust; emails have a way of getting forwarded. You’re going to have moments when you write angry emails; save the draft, walk away, and come back when you’re ready to delete it.
- 2.
Scale your formality with your audience, erring toward more when in doubt—emails to your best friend at the office can be unsigned one-liners, but emails to your VP should be pristine. Overdoing it can be stiff, drastically overdoing it can be tone-deaf, but usually erring toward more formality shows that you take your audience seriously.
- 3.
Looping in stakeholders shows respect; try to include people who have a reason to care about your subject so they don’t feel that business takes place behind their back.
The Importance of Links
Technical emails inevitably reference data and require heaps of context. Visionaries have blessed us with the perfect tool to assist our readers: the hyperlink. The more your readers have to strain to find the context to understand your email, the less they’ll understand it and the more annoying they’ll find it and you—but an in-line link for every mystery can keep you in their good graces. Reference an endpoint’s success rate? Link directly to the dashboard. Reference a system that not everyone may know? Link to its wiki page. Reference a feature of a database or language? Link to its documentation. All of the above can save your readers time, energy, and cognitive load. It’s doubly important for assertions that may be controversial; resolve your readers’ doubt as quickly as possible.
“Remove Me From This List”
Maybe this section can save you some embarrassment and fight an epidemic ravaging America’s companies—the “please remove me from this list” reply. Around once a month, you’re going to see an accidental email to a huge mailing list that you didn’t know you were on. You’re also going to see 15 people—literally 15—reply to the entire company saying, “I don’t work on this, please remove me from this list.” This is a mystery to me and others, because I’ve never once seen an email list you could unsubscribe from by replying to the entire list. Maybe you can unsubscribe manually in a Google Groups page, maybe you can email the list administrator, whatever—all I know is that replying to 10,000 employees won’t get you there.
Email Archetypes
This section will present templates for a few common emails you may find yourself sending. These aren’t the only options in these contexts, but if you follow these formats, at least in 2020, no one will look at you askance.
The Technical Announcement
Technical announcements start with a tl;dr, follow-up with more detailed explanations of their backstories, embed many links for context, and usually invite feedback and offer help.
Hi <group>,
tl;dr <thing is happening>. <people will experience some impact>
<background and motivation>
<thing is happening>
<summary implications for readers; what they really need to do; links to more detail>
<invite feedback and offer help>
<signature>
For example:
Hi all,
tl;dr SingleDB is deprecated for analytics; all analytics will be ingested to Snowflake by way of Kafka (using the AnalyticsClient). We have documentation for creating tables, emitting metrics, and backfilling data. The deadline to migrate is the end of Q2.
SingleDB has been our storage system for all data, including analytics, since the company’s inception. As we’ve started to produce a greater variety and volume of analytics, we want to move those data off of our production database to reduce interference with customer traffic, improve cost efficiency, and enable integrations with various warehousing tools.
Therefore, we are moving to storing analytics in Snowflake. Data will be logged to Kafka using our internal AnalyticsClient, then ingested to Snowflake from there. The steps for migrating data are:
Configure tables and ingestion in the warehouse as discussed here.
Adopt the AnalyticsClient to dual-write data. The client is already available in the monorepo. An example usage can be found here.
Backfill data as discussed here.
Remove existing writes to SingleDB.
This process is documented overall here. Our org-wide target to complete this migration is the end of Q2, and we intend migrations for feature teams to be quite easy. If you need help with this migration or have any concerns, please don’t hesitate to reach out to [email protected]. Thanks in advance for your help completing this migration!
Thanks,
DH on behalf of the Data Team
The Technical Question
You can use the principles from Chapter 14 to craft technical questions.
The Operational Risk
As discussed in “Bus Factor > 1” (Chapter 20), when we discover information of operational significance, we email it to our team. Here’s the template for doing so:
Hi folks,
tl;dr <tl;dr>
We’ve just become aware that <technical issue>. This implies that <operational risk>. <operator guidance>. We are working on a fix and will keep this list updated. Please reach out with any questions.
<signature>
For example:
Hi folks,
tl;dr App restarts are causing errors; please only restart if absolutely necessary.
We’ve just become aware that an issue in our load balancing configuration is causing user-visible errors when recommendation service instances are restarted. Zi and I are actively investigating, but in the short term, please do not deploy or restart unless absolutely necessary. Please reach out with any questions.
Thanks,
DH
The Project Status Update
People who care about projects usually care about two things: schedule (when things will be done) and downstream implications (how they can or must use them). That’s true for almost everyone you’ll need to update, from close technical collaborators to managers to VPs.
However, they’ll care about different levels of abstraction: leaders and distant stakeholders (say, the whole company) will care about the project level, that is, how the whole thing is going and the impact on stakeholders. Close collaborators like your project teammates will care about the details, the exact functionality you’ve built, and what they can do with it.
- 1.
Project background
- 2.
Progress
- 3.
Impact on stakeholders
- 4.
Schedule
- 5.
Plans
- 6.
Issues
The template:
Hi <audience>,
<project summary or background link> <key changes>. <overall status/schedule>. <any important announcements>.
Area 1: progress, impact, schedule, plans, problems
...
Area N: progress, impact, schedule, plans, problems
Thanks!
<you>
For example, an update to a large engineering list:
Hi folks,
The Snowflake migration (proposal) is estimated to be on track for completion by the end of next month. This month, we released the EventCompare tool that can compare events in the legacy system to tables in the warehouse; please use this tool to verify your migrations.
Event migrations: 16 of our 25 event types have been fully migrated, including deleting legacy event logging code. Follow our progress in this tracker.
Query migrations: all analytics UIs have been updated to support reading from either legacy tables or the new warehouse. See this doc for configuration.
Tooling: EventCompare was released to enable verification of new warehouse tables against legacy data. This tool has been used by four teams to verify updates.
As always, questions and feedback are welcome at [email protected].
Cheers,
DH on behalf of the Data team
In contrast, we might update a manager on a small slice of that project with a shorter, less structured email that still describes progress, acknowledges a small issue, describes the remaining work, and estimates the schedule.
Hi Umesh,
Quick update on progress this week. I’ve merged my PRs to emit history-page analytics to Kafka and do the Snowflake ingestion. EventCompare helped me catch one small bug, but after that fix things are looking pretty good, and the backfill is running now. I want to let this run for another week before deleting the legacy code, but I think we can likely mark this completed early in the week after next (the 22nd or 23rd).
Cheers,
DH
Finally, we might informally update close collaborators who know almost every detail of what we’re doing, focusing on fine-grained detail.
Hi Brandon and Jing,
I’m almost ready with the fix for the conflict-handling bug in the backfill tool; I plan to have a PR ready for you to review tomorrow. After that, I’ll start on the observability improvements we talked about, which should take the rest of the week, because I realized I’ll need to do small refactor first. Brandon, do you think you could take a look at the errors Sarah reported?
Cheers,
DH
Requesting a Meeting
When requesting a meeting from someone whose help we need, our main goals are respect and efficiency—show that you appreciate your help, and, to the extent possible, save them effort and confusion of any kind except showing up to dispense their wisdom.
We start with a concise sentence or two of background explaining who we are and what we’re working on; otherwise they’ll be confused (and therefore annoyed). We continue with a request for a meeting, explaining what we hope to discuss and accomplish. Finally, we touch on logistics; particularly, if you have the benefit of a shared calendaring system, you offer to take care of scheduling the meeting.
Here’s a template for a meeting request to someone you don’t know who works at the same company.
Hi <person>:
I’m on <team> and am currently working on <project>. Right now, I’m <working on part of project>, and <some reason to seek out their help came up>. [I realize you may not be the right person for this question; if I’m wrong, sincere apologies! Otherwise…]2 Would you mind if I schedule a brief meeting to <achieve specific goal>? Thanks so much!
Cheers,
<you>
For example:
Hi Simon,
I’m on the platform team and am currently working on our migration from Thrift to gRPC. Right now, the tooling is in a beta state, and we’re ready to start onboarding our first services.
We’re thinking that the inventory services might be a good place to start, since they’re using the newest versions of the RPC framework. Amy said that you have some of the best expertise in those services; would you mind if I schedule a brief meeting to discuss whether this is a good place to start, and if so, pick a first service? Thanks!
Cheers,
DH
The Intro Email
When introducing two people so they can collaborate in some way, we address them both in turn, providing context on the other party, then finish with a standard note about BCCing yourself (so they can continue the conversation privately).
Hi <A> and <B>,
<A>: <B> is <B’s relationship to you>, <background>, <optional quip>. <Reason for connecting you>
<B>: <A> is <A’s relationship to you>, <background>, <optional quip>. <Reason for connecting you>
I’ll leave you two to connect and move me to BCC. Hope you can catch up soon!
<signature>
For example:
Hi Ramesh and Wei,
Ramesh: Wei is a long-time colleague of mine on the Infrastructure team, an experienced network engineer, and all around hacker. She’s considering making a move to the StartupWithinAStartup team (that’s still not public knowledge) and wants to learn more about the team.
Wei: Ramesh and I worked together at FooCorp and then on the Security team right after I joined. He’s worked on the StartupWithinAStartup team for the last two years and has good insight into how the team operates.
I’ll leave you two to connect and move me to BCC. Hope you can catch up soon!
Cheers,
DH
Email Strategy
In most software jobs, you’ll receive a crushing volume of email—status updates, overly polished newsletters, 50 kinds of auto-generated reports and notifications, threads on large mailing lists, and, of course, the occasional request that really requires a response.
You’ll need a strategy for managing this deluge—for efficiently acquiring the information you need, discarding what you don’t, losslessly responding to what needs responding, and protecting enough time and focus to produce technology.
Keep Your Inbox Empty
Many engineers practice Inbox Zero, a strategy for managing the flood by keeping one’s inbox nearly empty. The strategy calls for acting on every email in one way or another in processing sessions, aiming to conclusively resolve most either by replying, archiving, or forwarding, and removing others from sight in a special folder for deferred processing if needed.
I don’t follow this method in all its details, but it’s well worth researching and considering. I did adopt what I personally consider its most important principle—I regularly drain my inbox all the way to zero, and I strongly advise you to do the same. This practice has two important benefits: first, you will never permanently miss an email because it is buried under a lot of junk you don’t care about, and second, it will give you a subjective sense of triumph over your email, flushing away the feeling that you have an ungovernable haystack to sort through and countless important emails you’re missing. I consider this more or less a special case of getting things done—fighting cognitive load and stress by ensuring that confidence that your system will always surface important action items. When you oblige yourself to act on every single email, you avoid the stress of whether you missed something.
Reduce Your Inbound
If you don’t need to read it, you should never see it. Companies are constantly creating mailing lists for every manner of automatic notifications, and most of them can be safely ignored. I find that it’s quite easy to spam-creep your way into spending your whole day archiving junk. The moment you recognize that a list isn’t necessary, you should send it directly to your archive or trash can.
Folders (Mostly) Don’t Help
When I first started getting a lot of email, my strategy was to route it into many topic-based folders and review those folders one by one. This made my problems much worse. Consuming all my mail required countless individual steps, I missed important mail as a result, and I felt a vague sense that I was constantly in the wrong folder, reading the wrong thing, and about to be scolded. This may be a good strategy for strictly optional mail—your newsletters and your semi-relevant updates, which you can easily miss—but you should not employ it for anything important. Send mail to your inbox and vigorously drain the queue—it’s the only way to be absolutely sure you haven’t missed something important.
I’ll note just one important exception: if your company’s email system doesn’t have powerful search functionality, you may have to do your own organizing after reading to support revisiting important messages.
Emails and To Dos
Email is not the place to keep your to-do list, because you’ll have to reexamine long-running to dos again and again and again, wasting your attention and subtly telling yourself again and again that you’ve failed to do them. As Getting Things Done argues, you should be pulling from the head of your queue with confidence and never frittering away your attention on things you aren’t going to do. Track your to dos in a dedicated app.
Email Cadence: The Power and Cost of Fast Replies
When you reply to an email instantly, it’s startling and delightful to your correspondent—their normal agonies of impatience evaporate, and you seem a paragon of dedication and energy.
On the other hand, constantly checking your email drags on your energy and focus—I don’t think it’s possible to write tricky code with constant email breaks.
I’ll offer you a few email schedules I’ve known colleagues to use, then describe my own dubious (but apparently maintainable) pseudo-system.
Some people use radically minimalist systems, like responding to email exactly once a day at the end of the day. I think this is admirable for coding productivity, and maybe it will work for you in your environment. I personally don’t think it’s acceptable to impose a p50 latency of 12 hours on my colleagues; I check more often.
Some people have disciplined systems for distributing processing throughout the day—for example, processing email at the top of the hour every hour. The argument for this system is that it both caps reply latency and limits interrupts. To me it seems sensible, but I can’t manage it—when I’m deep in something, the context switch is too painful.
The focused session, where I set out to drain the queue completely, send my more complex or tricky messages, and process a cornucopia of inanities.
The casual glance, where I process at most a couple of emails and see what’s doing literally right now (e.g., if someone has hit a serious problem I can help with). I may take the opportunity to try to surprise a colleague with a quick reply or promote the glance to a full session if something urgent and complex comes up.
The focused session demands an expanse of dedicated time, just like complex coding; it’s hard to start, hard to resume, and productive. The “glance” can be finely time-sliced, for example, while waiting for a long test suite to run.
My personal system is a focused session in the morning most mornings, then “glances” when I finish something or have a long waiting period in the course of my normal work (I do plenty of three-minute builds). I don’t hold myself to a high bar in my “glance” sessions—I try to shoot off a quick reply or two, process and archive what I can, and not get too deep into it. It’s a way to decrease latency for critical issues and gift colleagues a few unexpectedly swift replies.
I think doing my focused reading in the evening would actually be better for my productivity, because I do my best work fresh in the morning; when I’m in coding crunch time, I get straight down to it every morning. However, I find evening reading too psychologically difficult to systematize, because when I’m deep into my afternoon coding, it hurts to stop.