Technical Email Design
A good technical email design can save hours or even days of wasted time. This translates into dramatic savings for your business and highlights the unique value you can provide.
So what makes a good technical email design? Abundant clarity, liberal formatting, and thoughtful graphics are a good start.
Clarity
Clarity is king when designing technical emails. Therefore, like any good UX/UI designer we should be mindful of presenting information in an easily digestible form.
In contrast, how many emails have you received that were nothing but painful walls of text? The secrets of the universe might be contained in that wall of text, but you’d be hard-pressed to extract it in such a malevolent form.
Compare the following:
- “A good object oriented design should adhere to the five SOLID principles which are Single-Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion.”
- Good Object-Oriented design should follow SOLID principles:
- Single-Responsibility
- Open/Closed
- Liskov Substitution
- Interface Segregation
- Dependency Inversion
It’s clear which of these two approaches presents the information with more clarity.
Formatting
The previous example leads nicely into the topic of formatting. Above all, a little formatting goes a long way to making content more digestible.
We’re not writing English Lit essays here. Formatting and clarity should take precedence over literary flare.
There are a number of tactics we can use to clarify our writing. I’ve listed some of my favorites below.
While this is not an exhaustive list, it should be a good starting point. We certainly don’t need to deploy them all in every email, just pick and choose where it makes it sense.
Do Use:
- Lists (Bullet and Numbered)
- Headings and Subheadings
- White Space
- Indentation
- Bold, Italic, Colored, and Highlighted text
Don’t Use:
- Walls of text
- Long sentences and paragraphs
- Uncommon fonts
Graphics
Graphics can be an incredible time saver. Whether it’s a screenshot, a technical diagram, or a hacky MS Paint drawing.
We can often replace volumes of text with a simple graphic. It’s just more natural to understand a graphic compared to getting the same information from text.
Similarly to formatting, we have a number of tools available for graphics. Depending on the email’s audience we’ll of course prefer a different subset of graphics.
Screenshots are almost universally useful regardless of the audience, especially a sequence of screenshots for any application flow for example.
“I would recommend embedding content within an email whenever possible.”
Also I would recommend embedding content within an email whenever possible. Attachments are fine for large files as a reference, but it ruins the flow of a good email if your graphic content is attached and not embedded.
Moreover, common sense should be used when deciding whether to embed or attach. For example, embedding a 1000 line Excel table within an email will make you very unpopular. Knowing not to do this is unlikely to be a problem for anyone reading this site.
Finally, resizing or scaling graphics should also be done liberally. We rarely need a 1MB+ image when a 100KB will work just as well.
As remote Java devs, we should be conscious that not everyone is on a 1GB internet connection. Efficiently sizing our emails takes a minimal amount of effort and can make a big difference to our lower bandwidth counterparts.
Do Use:
- Screenshots
- Diagrams
- Code Snippets
- Embedded tables
Don’t Use:
- Attachments when you could embed
- Huge, un-resized graphics
Summary
A well-designed technical email should have clarity, formatting, and graphics. By minding these three concerns you can save yourself time and your employer money.
As remote Java devs, we should excel in our communications and writing clear, aesthetically pleasing emails are a great way to do so.
The payoff for writing good emails is avoiding unnecessary meetings and endless email volleys. These are time sinks and prevent us from providing the level of value of which we’re capable.
Everybody wins if we can avoid these for ourselves and ultimately for everyone who would have been sucked up in these gyres of futility.
The value of simplicity when writing business emails is highly underrated. In addition, our effectiveness depends on making our writings easy to digest. We can all increase the value we deliver to clients and employers by writing well.
It’s helpful to think of every email we send in terms of cost. For instance, a poorly written email can set off a chain reaction of delays and loss of productive time.
An average developer will wait for a meeting with the Product Owner to talk about the requirements with no pre-meeting email sent. After that, something like this usually occurs:
In contrast, a high-value dev will analyze the feature request and write an email with the likely use cases and implications. This gives the Product Owner and the developer a common context. They can subsequently iterate over any disparities much more directly, clearly, and quickly. 
There is a bit of magic that happens when we write things down. I don’t know the psychological reasons for it, but the act of translating concepts from our minds to a physical medium enhances understanding markedly. 
Having a common context in which to examine a problem is tremendously useful. It’s also one of the biggest benefits of email. It’s a shame that email is too often neglected for this purpose. And is instead often used for other trivialities.
I remember when I started my first programming job over 15 years ago. There was a Team Lead who’d been with the company 30 years.