Ryan Macklin - So you need to give bad news to users…

This is a summary of a talk given at Write the Docs Prague 2021.

Ryan Macklin is a technical writer and Good Docs Project contributor, joining us from Michigan. He considers himself an empathy advocate. 

His focus is on writing for people who aren’t in calm, receptive states of mind. His suggestion is never write for calm people, but people in emotionally activated states. If he gets it right for those people, he’ll get it right for the calm people as well. 

1. Understand dysregulation

The states we’re in when we’re emotionally activated are important to understand. The amygdala deals with emotional states, but when it gets out of control it floods our brains and bodies with all sorts of chemicals. When that happens, prefrontal cortexes can’t engage until the flood subsides. 

We all get dysregulated. Some of us may be more prone to it than others in certain contexts.

We’re bad at compartmentalizing. We might project an earlier annoyance onto another, unrelated issue. We can never know if people are dysregulated because of the bad situation or if they were already activated in some way. 

People feel inconvenient things at inconvenient times. The anxious brain crowds out energy for everything else and we have reduced cognitive bandwidth. Even though the conscious brain knows this state isn’t helping us, it can’t deactivate itself. 

These states of mind also have a distorted sense of time. We have difficulty in processing information. 

2. Highlight action

When you have an action you need users to do, make that action easy to find, understand and accomplish. Highlight the action as boldly as possible by making it the subject line, bolding the action, and using a button to link to the action. 

He uses the “brain spending” analogy to illustrate that users have a limited amount of brain energy to spend. The anxious person also has to spend brain energy since anxiety is very mentally expensive. 

We spend brain cash on things we don’t realize we’re doing and that depletes our brain energy. Brain energy fluctuates every day and if we spend more than we have, we go “brain-broke”. 

3. Show humility & respect

As we add different sorts of statements to documentation and organize them, we’re changing the costs involved in the different threads. Some threads weigh more than others and cost more brain bucks. 

Something in our brain responds to reassuring statements. You can include an apology to soothe frustrated people who are looking for an outlet for their energy. 

Our goal in empathy advocacy is to make life easier for some users without harming others. 

4. Giving a time frame

WIthout giving a time frame to your users you’re creating a vicious void for your users. They have lots of terrible thoughts waiting for you to run out of energy and fall in. They’re going to pull you down, especially if they're associated with past trauma. 

You need to strengthen the bridge over the void, and get engineering to understand that we need to do this. If your system has technical difficulties, give users as much information as possible to do with the problem. 

“If we don’t advocate for our users, no one will.” 

5. Apologize with bravery

Many apologies are weak because we don’t want to seem liable, afraid of looking weak, and we don’t know how to apologize well. 

Collectively, users are sharper than we often give them credit for. We need to apologize with bravery and strength: 

• Use direct language

• Put ourselves in unpleasant spotlight

• Show a commitment to resolution

If we can default to apologizing with bravery and strength, some of those sharp users will witness you being genuine and this has benefits for your brand. 

Final remarks

So remember, write for the user who is anxious, frustrated, or upset. If you write with those users in mind, the content will also benefit everyone else. 

Understand the states of mind these users are in to cultivate empathy. Make your technical writing clear and to the point. Highlight action, show humility and respect, give a time frame, and apologize with bravery. Your users will thank you. 

Listen to the full talk here.