Recommended
Recommended
More Related Content
Recently uploaded
Recently uploaded (20)
Featured
Featured (20)
Better Documentation Through Empathy
- 1. Better Documentation Through Empathy Eva Parish Senior Technical Writer, Squarespace Photo by David Clode on Unsplash www.evaparish.com
- 2. You are the best person to write these docs Photo by Daniel Hjalmarsson on Unsplash www.evaparish.com
- 3. Empathize with your audience Photo by rawpixel on Unsplash www.evaparish.com
- 4. Empathy: the ability to imagine what someone else is thinking or feeling Photo by Sime Basioli on Unsplash www.evaparish.com
- 5. Photo by Sharon McCutcheon on Unsplash www.evaparish.com Imagine why they're reading in the first place
- 6. A note about these four types of docs ● Service overview ● Tutorial ● Reference ● Troubleshooting Photo by Lucas Davies on Unsplash www.evaparish.com
- 7. "What is this product? Should I use it?" Service Overview Photo by Emma D. on Unsplash www.evaparish.com
- 8. "Should I even be reading these docs?" Service Overview Photo by Emma D. on Unsplash www.evaparish.com
- 9. Imagine you are this user. What happens if you can't find what you need? Service Overview Photo by Emma D. on Unsplash www.evaparish.com
- 10. "I want to do X. How do I do X?" Tutorial Tutorial Photo by rawpixel on Unsplash www.evaparish.com
- 11. Who are tutorials for? Tutorial Tutorial Photo by rawpixel on Unsplash www.evaparish.com
- 12. What doesn't belong in a tutorial? Tutorial Tutorial Photo by rawpixel on Unsplash www.evaparish.com
- 13. "What are all of my options?" Reference Photo by Kelly Sikkema on Unsplash www.evaparish.com
- 14. Who are reference docs for? Reference Photo by Kelly Sikkema on Unsplash www.evaparish.com
- 15. What would you want in a reference? Reference Photo by Kelly Sikkema on Unsplash www.evaparish.com
- 16. Photo by Garry Clarke on Unsplash "What the heck does this error message mean?" Troubleshooting www.evaparish.com
- 17. Photo by Garry Clarke on Unsplash How do you help yourself in this situation? Troubleshooting www.evaparish.com
- 18. Photo by Garry Clarke on Unsplash Use structure to help users help themselves Troubleshooting www.evaparish.com
- 19. Use empathy to imagine what your audience needs Photo by Jon Moore on Unsplash www.evaparish.com
- 20. ● Service overview – "What is this product?" ● Tutorial – "How do I do X?" ● Reference – "What are all of my options?" ● Troubleshooting – "What does this error mean?" Photo by Kent Pilcher on Unsplash www.evaparish.com Recap Thank you! Eva Parish
Editor's Notes
- As an engineer, you know that writing documentation is important. You may not like doing or, or you may find it difficult, but you know that it’s part of your job (and it is part of your job, by the way).
- Here's the thing: you already know how to write these docs. You have all the knowledge, you just have to shape it. That’s where I can help.
- I have a whole list of documentation best-practices, but most of them can be simplified to empathizing with your audience.
- Empathy simply means the ability to imagine what someone else is thinking or feeling. This can be applied in different ways. But since I have limited time, I want to talk about one practical application of this.
- People come to documentation for different reasons. Most people don’t read documentation for fun (although that would be cool), they read it because they need something. If you figure out what that is, that will affect how you write. You will structure different pieces of documentation differently, based on the information people want out of them.
- A note: the four types of docs I'll mention here are just that -- four options. Not every set of docs will need all four, nor are they the only types of docs out there. The thing to take away is that they each solve a different question for the user.
- So, the first type: service overview. Imagine someone has just stumbled across your docs. They want to know "what is this product? Do I want it? How does it compare to the alternatives?" If you're writing for an internal audience, the questions may look more like "What is your team responsible for? Who should I talk to if I have a question about this one service?"
- Essentially, the service overview answers "Should I even be reading these docs?"
- Imagine that you as a user are looking for this kind of information and can't find it -- you're likely to just give up and move on to some other product. That's why service overview type information should be prominent, easy to find, and early in your documentation.
- Next: tutorial. A tutorial is a guide to one specific task, formatted as a numbered list of steps. A good tutorial will also tell you the prerequisites of the whole procedure, the expected outcome of each step, and where you can go next.
- A user who needs a tutorial is often new to doing whatever it is the tutorial is about. They don't need a comprehensive list of all their options ever. They want one specific, usually simple path through whatever the topic is.
- Then once they're confident with that, they can lose the training wheels and start exploring other possibilities.
- Which brings us to reference-style docs. References and tutorials go hand-in-hand. Where tutorials provide you the one simple path, reference materials list every possibility. API documentation is a kind of reference: it will tell you every endpoint and return value of a service, but it won't walk you through how to create a simple plugin with those.
- That's why reference docs are usually for advanced users, people who already know basically what they want to do. Imagine you're writing some code and you can't remember the name of that one method; you'd consult a reference.
- How would you want that to be organized? You'd probably want things listed in alphabetical order or with some other logical grouping. You'd want it to use tables or bullets or somehow organize it in a way that lets you skim within a page, or even better, search or filter within the reference.
- Finally, we come to troubleshooting docs. We've all been there. You come across a really cryptic error message and have no idea where to start looking. Try to imagine what would help you in that situation.
- One move is to grab the text of the error message and google it, right? For internal docs, you can't necessarily do that, but what you CAN do, as a doc writer, is compile a list of error messages that includes the exact text from the message, and then list out the solution for each one.
- If you stick them all in one long page, it's dead simple for a user to navigate to that page and Ctrl+F to search for a snippet of their error text.
- To sum this all up: think about the kinds of questions users are going to be asking when they look for this kind of information. Imagine that you are that user. What are you thinking and feeling at that moment? What kind of structure would help you locate the answers? And write from there.