404: Empathy Not Found

Every documentation failure has a technical explanation. The heading structure was inconsistent. The error message did not suggest a fix. The getting-started guide assumed the reader already had the environment configured. The warning was buried three paragraphs below the command it was warning about.

But underneath every one of these failures is the same root cause: the writer forgot what it felt like to not know the thing.

This talk is about empathy as a documentation practice, not the soft, abstract kind, but the specific, actionable kind that changes how you write an error message, structure a tutorial, or decide what context to include before a code example. As a technical writer at Red Hat and an open source contributor, I have audited documentation that was technically correct, structurally sound, and completely useless to the person who needed it most because it was written from the inside out rather than the outside in.

We will look at four concrete places where empathy breaks down in documentation: the assumptions we bake in without declaring them, the context we omit because it feels obvious, the error guidance we write for ourselves rather than for someone in a panic at a broken terminal, and the accessibility failures that signal to entire categories of users that this documentation was not written for them. Each failure mode gets a real example, a diagnosis, and a fix.

The talk is structured around a simple provocation: the user who cannot follow your documentation is not failing. Your documentation is failing them. And in open source, where documentation is often the only onboarding a new contributor or user gets, that failure has a direct cost to community health, contributor retention, and the long-term sustainability of the project.

Empathy is not a personality trait. It is a skill, and it can be taught, practised, and built into review processes. This talk shows you how.

1. The four specific places empathy breaks down in technical documentation are assumed knowledge, missing context, poor error guidance, and inaccessible design, with real before and after examples

2. How to audit your own documentation for empathy failures without needing user research infrastructure, practical techniques any contributor can use today

3. Why "the user is confused" is rarely the right diagnosis and how reframing documentation failures as empathy failures changes how you fix them

4. How to build empathy checkpoints into documentation review processes so that individual writers do not have to carry the entire cognitive load alone

5. A reframe of documentation quality from correctness and completeness to usefulness and welcome, and what that shift means for how FOSS projects prioritise their writing work