Empathy advocacy: Designing docs for all emotional states with Ryan Macklin

The Not-Boring Tech Writer

Learn how Ryan Macklin's "empathy advocacy" framework helps you design documentation that works for users in all emotional states (e.g. anxious, frustrated, exhausted, and curious/distractible) rather than assuming everyone comes to your docs in a perfect state of clarity.

Ryan and I discuss his unique path into technical writing, starting from his early computer hacking days and role-playing game writing background. Ryan explains how writing and editing tabletop games taught him that documentation is harder than technical writing because it requires creating user interfaces for "disconnected, squishy brains" while making content engaging enough that users won't simply abandon it for alternatives. This experience, combined with his personal journey through therapy and understanding neurodiversity, eventually led him to develop the empathy advocacy framework.

Our conversation centers around Ryan's empathy advocacy concept, which focuses on writing for users who aren’t calm. These users might be in four key cognitive states: anxious, frustrated, exhausted, and curious/distractible. Rather than designing documentation for the "happy path" or optimal users, Ryan advocates for considering people who may be dealing with high ambient stress, acute stress from urgent problems, cognitive depletion, or distractibility. The "stupid users" developers complain about are often just busy, stressed people whose brains aren't optimally processing information.

We explore practical applications of empathy advocacy concepts, including strategic screenshot reduction to minimize cognitive load, restructuring and tightly scoping FAQs to avoid information architecture problems, and understanding that every element in documentation has a "tax" on your user’s mental energy.

The episode also includes practical advice on social capital management, documentation stewardship, and the importance of "failing forward" rather than getting stuck in perfectionism.

About Ryan Macklin:

Ryan splits his cerebral time between tech writing, UXing, coding, and game design. By day, Ryan writes and edits software and hardware requirements. Otherwise, he works on game or tooling projects, light woodworking, and land improvement projects on his homestead in southern Michigan. Warning: Ask him about UX in games, and he may talk your ear off.

Resources discussed in this episode:

• empathyadvocacy.org
• Ryan Macklin talk: WTD ECQ Nov '22: 7 doc techniques rooted in empathy advocacy
• Ryan Macklin talk: How to avoid "toxic tennis" — empathy in user communication
• Other technical communication talks by Ryan Macklin

Join the discussion by replying on Bluesky

—

Contact The Not-Boring Tech Writer team:

We love hearing your ideas for episode topics, guests, or general feedback:

• Email: [email protected]
• thenotboringtechwriter.com
• LinkedIn
• Bluesky

Contact Kate Mueller:

• knowledgewithsass.com
• LinkedIn
• Bluesky

Contact Ryan Macklin:

• Ryan's newsletter: buttondown.com/ryanmacklin
• macklin.cc
• LinkedIn
• Bluesky

Contact KnowledgeOwl:

• knowledgeowl.com
• LinkedIn