Better Documentation through Empathy: or, How to Not Answer the Same Questions Over and Over Again

Here’s the step that most people miss when documenting their product or process: they fail to empathize with their audience, and this leads them to either write the wrong doc or hide the right information somewhere their users will never find. Instead of saying “What do I know about this topic?” and writing that down in a blob, you should say “What does my customer/user/team want to know?” It’s a simple shift in perspective that will make your docs wildly more useful and easier to navigate. For example: you should structure your docs differently if your users are asking “I’ve run into this error message, what does it mean?” vs. “Should I be using X product or Y product for my use case?” vs. “What is that endpoint for that one thing I want to do…?”

In this talk I’ll cover why and how to put yourself in the place of your users, and go over four common types of documentation and when to use them (service overview, tutorial, reference, and troubleshooting).



Eva Parish

Eva Parish is a Senior Technical Writer at Squarespace.