Empathy in documentation

How empathy helps us write better documentation.

A discussion on the Write the Docs Slack got me thinking about empathy in tech in general, and documentation in particular.

"Empathy" is a term that appears in tech frequently. From UX design to marketing to documentation, we talk about empathising with our users. Yet it isn't always easy to achieve, or even clear what it means.

Sympathy vs empathy

empathy: the ability to understand and share the feelings of another.
sympathy: feelings of pity and sorrow for someone else's misfortune.

This article on empathy in UX draws a distinction between sympathy and empathy. "Sympathy" implies distance, "empathy" is closer, and affects us emotionally. An empathetic tech writer doesn't just note the users' struggles and pity them, she feels moved by their pain points and is emotionally motivated to help.

Do you need to be a developer to have empathy for developers?

No.

To return to the Slack discussion that prompted this post, someone (playing devil's advocate) posed the following question comparing developers and tech writers:

"Aren't developers who write for developers on SO (StackOverflow) and GH (GitHub) more empathetic?"

I found myself responding:

"StackOverflow is a fantastic resource, but I wouldn't say empathy is its defining feature . . . I don't think empathy is just 'being familiar with someone's problem', it's being able to grasp the intellectual and emotional struggle of the question-asker, and respond to both."

For example, an answer on StackOverflow that provides a technical solution but includes a comment on the foolishness of the question isn't empathetic, even though the respondent has a good intellectual understanding of the technical problem.

While a developer may be familiar with common dev frustrations, they may not be skilled at turning this into empathy for others. More experienced devs may forget how it felt to be a beginner. Or they may fail to extrapolate: if someone encounters a specific problem they also had, they may empathise, but not be able to take the next step to empathise with problems they themselves haven't faced. To empathise with a wide range of users, you need imagination.

Learning empathy

In wonderful synchronicity, a few days after I originally wrote this post, a friend published her own post, The gift of empathy. It describes how her social worker training helped to develop empathy skills - I highly recommend giving it a read!

Empathy and imagination

Imagination is key to empathy when working on a tech product. You may have things in common with some of your users, but it's likely there are also sizeable differences: in background, emotional responses, technical knowledge and experience, and in the goals different users have with a product. Practice empathising with people different from yourself (this is good general life advice too!) Just because you find git, or JavaScript, or writing, easy, doesn't mean everyone will. When meeting someone who's struggling with something you think is easy, consider how you felt on a task that was challenging for you, and create your response from that feeling.

Empathetic documentation

So do we need to start all our docs with "so sorry you're having this problem, I share your frustration"? No! In fact, that would probably make things worse.

Empathetic documentation starts by being good documentation: clearly written and well organised. Empathy comes into the process when choosing what assumptions to make, what content to include, and how to structure your material.

Assumptions

You have to make assumptions about your audience. Let's say you're documenting a niche medical software package. Your users are going to be nurses, doctors and surgeons. You can assume a high level of medical knowledge. When documenting how to use a feature that, say, monitors the levels of a drug in the bloodstream, you probably don't need to walk through how to do a blood test first. You can assume that knowledge. If you don't make assumptions, your documentation will suffer: it will become an unworkably massive project, hard for you to maintain, and hard for your users to navigate.

Empathy can help you check your assumptions. Sometimes it may be clearly defined (as in the example above, where you have a very limited user base), but sometimes it may be less obvious. When documenting an API, are you certain that all the developers using it are thoroughly familiar with REST principles? Or could you also have entry-level developers or students using your API? Consider the struggles your most inexperienced users face. This doesn't mean supplying a comprehensive introduction to REST right in your docs (although that could make for a great piece of content marketing), but perhaps you can provide a link to a suitable tutorial.

State your assumptions, or to put it another way, provide context. Who is this document for? What are the knowledge prerequisites?

Content focus

You can't document everything. Moreover, you probably shouldn't document everything. Empathy helps you narrow your focus: which points in a workflow cause frustration? Which concepts are confusing users? Focus on these. You can do this before a product launches by mapping out what tasks users are likely to focus on, and making sure you support them. After launch, make sure you are aware of customer feedback and support queries, and ensure your docs help users with their most common problems.

Content structure

Here we enter the realm of UX and information architecture. Without becoming an IA expert, you can still note how you respond to different ways of organising content. What do you find browsable? What do you find confusing? Then extrapolate from that, for example: "It's easy for me to search this content and find the article I want because I am familiar with the term 'information foraging', but what if I wasn't? What if someone was looking for 'articles about how people find information'? Would my documentation structure allow those people to search or browse to what they want?"

Beyond the docs

Empathy is a key part of being a decent human being, including on the internet. The first rule of netiquette is "remember the human". Always keep in mind the real, complex, individual humans behind the usernames and anonymous interactions. This applies to your product's users (and your documentation's readers), as well as to interaction on forums, Slack, Discord and so on.