So you need to give bad news to users…




A lot of documentation advice talks about happy path docs, and sometimes abstractly about users who struggle. This talk focuses on actionable tips for when you have to give users bad news—whether in error messages, email comms, or support docs.

The focus is on servicing a broad range of users' psychological states and needs during times of distress and disconnection, primarily anxiety, frustration, and exhaustion. Some tips I want to bring up (along with the basics of how they work psychologically):

Include time frames for resolution — people in anxiety live in a different temporal state than people who are calm, so holding their hand in understanding a future state is important for a sense of psychological safety

Be brave about when a given situation is difficult — frustrated people are often in a combative state looking for some way out of that emotional state through vindication, and being acknowledged is a way they can help themselves regulate

Highlight the action to be taken (even if that action is "wait") — exhausted people struggling to be engaged or those anxious about what to do next need a clear understanding of next steps, and unclear directions will lead them astray

While some of these may seem "obvious," my talk is about why they work, and the empathy advocacy I want to help spread in the documentarian community.

  • Conference: Write the Docs Prague
  • Year: 2021

About the speaker

Ryan Macklin (he/they)