Simplicity, Clarity, Empathy: A Q&A About Documentation with Hederis’s Nellie McKesson and Erica Warren
As part of our spotlight on documentation, we’re thrilled to be able to share some insights from Erica Warren, who oversees operations at Hederis, and Hederis CEO Nellie McKesson. Nellie and Erica first met working at Macmillan, where they collaborated on projects that planted the seed for the Hederis app. In this Q&A, they share some insights about how to create effective software documentation from a place of empathy and humility.
Q: Nellie, you said to me that writing documentation is “all about empathy” — can you elaborate on that a little bit?
NM: I feel like it’s really easy, when you’ve figured out the solution to a problem, to forget about all the pain and frustration you went through, and all the red herrings that you followed to find that solution. But when you’re writing documentation, remembering all of those things is so important. At minimum, write for the person that you were when you first started trying to figure out how to solve your problem — pick out all the important things you learned on your journey, and then present them in your docs in the order you wish you’d learned them. Even better, write for the person you were before you even knew this problem existed, before you knew anything about it. How would you describe the problem to a beginner? How would you help them get to the point where they can understand what you’re showing them? Put yourself back in the shoes of a beginner and have empathy for that person.
At minimum, write for the person that you were when you first started trying to figure out how to solve your problem. Even better, write for the person you were before you even knew this problem existed, before you knew anything about it.
Q: You both worked together building the Bookmaker toolchain at Macmillan and developing the Hederis app, which are both tools for people working in book publishing. Do you see any special challenges with creating documentation for a publishing audience, some of whom are, shall we say, not super tech-savvy?
NM: Yeah, there was an interesting variety of challenges. One of the big ones for me was finding a way to write documentation that could work for everyone who might use the tools. Publishing workflows tend to be relatively siloed — editors have their tasks and the things that are important to them, and production folks have different tasks and priorities, and designers have their own tasks and priorities, and so on. There’s overlap, for sure, but also plenty of individualism among the different roles. So, the challenge was finding the words that would jump out for each group of users, to help them understand both what problem I was trying to help solve, and also why it matters. For example, an editor might not initially understand why its important to label their paragraphs as headings, body text, etc., but for the comp designer who is laying out the text, this is a crucial step in the process. So we had to find a way to both explain why certain things matter to folks who haven’t had to think about those things in the past, and show them how to do it, without bogging them down with too many technical details or tangents.
That also leads to another problem that was maybe more of a personal learning experience for me, which is that I come from a technical background, and speak a technical language that isn’t familiar to a lot of people. So I had to teach myself to explain words that were a regular part of my vocabulary. Like, saying “Consider good semantics as part of your manuscript tagging process” isn’t going to be as effective with this audience as saying “It’s important for computers to know whether a block of text is a heading, extract, plain text, etc., so that it can decide what to do with that block of text.”
EW: In addition to Nellie’s points, one thing I learned working with the team at Macmillan is that different people learn best in different ways. Some people want to read the documentation first so the app is more familiar when they try it. Some people want to just dive in and click buttons, and ask questions as they come up (which our chat support is great for). Other people respond better to short video lessons, or by working on a real project. If someone doesn’t respond to one kind of learning, it’s more an issue with the materials than the person.
Another challenge is really about humility, I suppose. If you have written documentation about a specific topic and yet people still struggle with it or ask a lot of questions, the issue isn’t that people just need to read the docs — its that the docs aren’t serving these folks well. Maybe the docs aren’t clear enough, or aren’t written for the correct audience. Maybe more illustrations would help. Even if it is because people don’t want to read the docs, the answer is usually to offer the information in a way that people want rather than blaming users for not meeting your expectations.
If you have written documentation about a specific topic and yet people still struggle with it or ask a lot of questions, the issue isn’t that people just need to read the docs — its that the docs aren’t serving these folks well. Even if it is because people don’t want to read the docs, the answer is usually to offer the information in a way that people want rather than blaming users for not meeting your expectations.
Q: What are some pet peeves that you’ve encountered in other documentation that you try to avoid in your own?
NM: One of my biggest pet peeves is when people make assumptions about a person’s knowledge level coming into the article, and don’t give any resources for building foundational knowledge that might be required. I see this in a lot of very technical documentation, where the author will jump in and assume that you already know certain things, and throw around words or acronyms with no explanation of what they mean. This is super frustrating as a user, and makes the documentation effectively useless, since it actually creates another barrier to entry, rather than opening the door and welcoming folks in, so to speak. I think these days, you have to assume that folks are coming to your documentation article from Google rather than reading through all your articles in order; make each article either capable of standing on its own, or tell people specifically what they need to read first before they can tackle the article you’ve written. Also try to avoid writing anything that makes people feel like they have to “tackle” it, haha. Documentation should make things easier.
EW: I get frustrated when documentation is too dense and/or detailed. Simplicity, brevity, and clarity should be the goals (even if those can be deceivingly difficult to achieve). Writers should assume that people are going to be jumping back and forth between their documentation and using the app itself, so long paragraphs of text, or jumping into asides, isn’t helpful to the user who now has to find their place. Sometimes it’s just an issue of breaking up a long instruction into more, smaller steps. Sometimes it means breaking up a long article into more sections. We need to recognize that people are often looking to quickly scan an article to pinpoint the information they need, and the more waypoints we have for them to do that, the better.
Q: Erica, this question is for you: Developers will approach the writing of docs from a certain perspective. Do you see folks on the operations side as having different ideas of what makes good documentation?
EW: From a business perspective, everything comes down to getting more users — and the best way to do that for us is to create a really high-quality user experience. Solid, useful, up-to-date documentation is a huge part of that. We can create the most groundbreaking features in the industry but if folks don’t know how to access them, they may as well be nonexistent.
Good documentation is also a huge asset for acquiring new customers — they are often the first opportunity we have to communicate about the app with people who might be interested in trying it. Checking out the docs is an easy, low commitment way to get a better sense of not just the specifics of using the app, but also of our customer support mentality. Clear, helpful documentation is a signal that we take customer support and user experience very seriously.
Good documentation is a huge asset for acquiring new customers — they are often the first opportunity we have to communicate about the app with people who might be interested in trying it. Checking out the docs is an easy, low commitment way to get a better sense of not just the specifics of using the app, but also of our customer support mentality.
Q: For a user who’s created a Hederis account but hasn’t started their free project yet, or has considered the app but is not sure how to get started, which Hederis resources do you recommend to motivate them take that next step and get to know the app?
NM: We actually have a list of “Featured Articles” on our docs homepage (docs.hederis.com), and they are all great things to check out if you’re a new user. There are a few things we do a bit differently than software like InDesign, so I’d definitely recommend reading up about styles, locking, and the “Limit these changes” menu. The Quickstart page is also a good place to look — it highlights some useful docs for different phases of the Hederis book production workflow.
EW: Folks are also always welcome to contact us at sales@hederis.com if they have specific questions or to schedule a virtual info session. We’re happy to demo the app, discuss the needs specific to your workflow, or just help you out in getting started on a free project.
