Empathy advocacy: Designing docs for all emotional states with Ryan Macklin
🎓 Our host, Kate Mueller, is teaching a 4-session Information Architecture Master Class that starts on September 16th!
🎧 TNBTW listeners can use the coupon code "NOTBORING" during checkout to save 40% off the list price!
🔗 Read more info and sign up: thenotboringtechwriter.com/learning
—
🎧 TNBTW listeners can use the coupon code "NOTBORING" during checkout to save 40% off the list price!
🔗 Read more info and sign up: thenotboringtechwriter.com/learning
—
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.
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.
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:
Contact Kate Mueller:
Contact Ryan Macklin:
- Ryan's newsletter: buttondown.com/ryanmacklin
- macklin.cc
- Bluesky
Contact KnowledgeOwl:
Creators and Guests
Host
Kate Mueller
Kate is a documentarian and knowledge base coach based in Midcoast Maine. When she's not writing software documentation or advising on knowledge management best practices, she's out hiking and foraging with her dog. Connect with her on LinkedIn, Bluesky, or Write the Docs Slack.
Producer
Chad Timblin
Chad is the Head of Operations for The Not-Boring Tech Writer. He’s also the Executive Assistant to the CEO & Friend of Felines at KnowledgeOwl, the knowledge base software company that sponsors The Not-Boring Tech Writer. Some things that bring him joy are 😼 cats, 🎶 music, 🍄 Nintendo, 📺 Hayao Miyazaki’s films, 🍃 Walt Whitman’s poetry, 🌊 Big Sur, and ☕️ coffee. Connect with him on LinkedIn or Bluesky.
Guest
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.
