January 9, 2023

Writing a great support email: structure

Mens sana in corpore sano

This is the second part of a series on writing great support emails. Part 1 covered the content of the email; this one is all about structuring the email for maximum clarity and readability.

Now we’ve got a clear list of topics to cover, what to say about them, and requests to make of the customer, let’s look at structure: making your message both understandable and straightforward to read. While related, those are actually two different things! An understandable message is grammatically correct, contains no typos, and is free of jargon or other difficult-to-understand terminology or sentence structure. 

But none of these things guarantees clarity: a clear message can be read end to end without confusion. All major points are both visible and comprehensible. Specific requests or responses to questions are prominent.

You can maximize the chance that your email will be read and understood by making it as easy as possible for the recipient to digest and respond.

There are as many ways of writing a clear, readable message as there are authors. Here are a few guidelines that I have found to be particularly helpful in writing support messages:

• Use whitespace to your advantage. A series of small paragraphs is easier to read than one long wall of text.

• Use lists: bullet points and numbered lists, like this one, when discussing related items. They are more digestible and clearly separate different thoughts.

• If you have several requests, make them clearly separated. Many folks will read and respond to just the first question and ignore the rest, which can be incredibly frustrating on both ends of the communication.

• Make sure there’s a logical flow. If one point depends on another, introduce them in order. Don’t introduce non-sequiturs.

As an example, consider this email.

Hi Aloysius,

Thanks for writing in. I took a look at your account and determined that your SSO settings are incorrect. Can you take a look at them and let me know if anything was entered incorrectly? Also please grab your application logs and send them along, since that will often give us more detailed troubleshooting information. You can also read our SSO guide here. Also don’t forget that you can click the ‘test’ button to see if your settings are right! We commonly find that either the required URLs are set incorrectly, or there is a copy/paste error in the secret keys, so check there first.

Thanks, 

Andy

By following the above guidelines, we can rewrite it to something a lot easier to follow.

Hi Aloysius,

Sorry to hear you’re running into trouble with your SSO setup. Looking at the settings from our side, it appears as though the SSO provider is set up incorrectly. Can you try the following?

• First, please send along your application logs (you can find instructions here for collecting those logs) so we can dig in further.

• Check all the fields again - a typo or copy/paste error is a common cause of failures. Consult our SSO guide if you have any questions about what goes where.

• Once you’ve done that, click ‘test’ to get immediate feedback on whether everything is working!

If things still aren’t working, let’s hop on a screenshare to do some live troubleshooting.

Standing by to assist further,

Andy

The order is much more logical, there’s a specific set of steps to follow, and I’ve offered additional paths forward if the provided instructions aren’t enough. By frontloading the request for more information, and providing instructions, it also makes it more likely that the customer will notice and respond to the request.

Keep in mind, of course, that clear emails aren’t a cure-all! Even if you do all of this, some folks just aren’t going to read your carefully crafted message, or will just read the beginning, or will completely misunderstand. You’ll just have to learn to live with that. But you can maximize the chance that your email will be read and understood by making it as easy as possible for the recipient to digest and respond.

Next time: tone and other intangibles

Thanks for reading Andy's Support Notes 💻💥📝!