At Reveal, we love all things data. To the extent possible, we try to run every facet of the business using data-driven decision-making, constantly trying to deduce the answers to two questions:

1. Why did this/did this not work?
2. What does our data tell us we can do to improve it?

One of our longest-running studies is on the efficacy of the user guides our platform and users create. While academic teaching efficacy is a very well-studied field, teaching someone how to use a software tool isn't nearly as extensively explored.

There's a wide array of literature on the subject of human<>technology interaction, often used as inspiration for UX patterns and further UX research. So far, so good. That's definitely an area where we still have a way to go (at what point will we say goodbye to point-and-click interfaces?).

However, answering the deceivingly simple question of "How should I write this so it maximizes my end-users' value (of the tool)?" is, in our opinion, understudied.

To curtail expectations, we do not claim to have a magic bullet answer to this question. What we do have, however, is a set of guides and rules that we have proven to increase the effectiveness of a user guide or, put differently, improve how much value your end-users unlock from a digital tool.

How Have We Measured Impact

We've taken a reasonably pragmatic approach to quantify whether one guide performs better than another; in short, what we do is:

1. Quantify the number of users who indicate the guide was helpful.
2. Measure the time it takes for a user to complete the workflow the guide covers before and after reading the guide.
3. Analyze support tickets, feedback, and survey comments to determine the number of users who had outstanding questions about the workflow after reading the guide.

Our Style Guide

With this in mind, here are our current best practices for creating an optimized user guide. A style guide for user guides, if you will:

1. Clear naming. Keep it short (40-90 characters) and descriptive (start with "How to" or the name of the feature or workflow you're describing)
2. Start each guide with a summary. Lay out what the guide contains and what the user will learn. It may sound repetitive (after all, the summary is just an abbreviated version of the guide!), but repetition is a powerful tool, and it communicates clear expectations to the user.
3. Include a table of contents in the guide. Ensure your users can jump to the most relevant section instead of having to scroll through the entire guide.
4. Use step-by-step instructions. Write the content using clearly labeled steps rather than free-flowing prose. This keeps the guide structured and makes it easy for the user to understand the sequencing.
5. Limit the guide to 6-8 steps. Our attention span is limited, and the efficacy of a guide tapers off rapidly with its length. It's often better to break up long guides into multiple ones to keep each snippet shorter.
6. Merge steps where possible and provide context in callouts. A good example is that instead of adding individual steps for each field a user needs to fill out in a form, add one step highlighting how they need to fill out the form, accompanied by a callout that discusses required vs. optional fields.
7. Provide images with annotations for each step. As far as guide efficacy goes, what they say is true: a picture says more than a thousand words. Adding a screenshot with annotations (highlighting the part of the screen you're referring to) alongside your step instructions is almost always beneficial.
8. Link to related articles in the body of the text. Software applications are intrinsically intertwined, and most workflows assume some degree of prerequisite knowledge. Make sure you link to all of these prerequisites in the body of the article. Great guides have, on average, 2-4 links.

Next Steps for Reveal

At Reveal, we're trying to create a tool that empowers users to operate technology and software tools confidently. A next-gen customer experience platform. Armed with this data, we're hard at work building a user guide validator to help you write guides that have been statistically proven to perform.

If you want to learn more about how Reveal can help you transform your internal and external enablement, don't hesitate to reach out!