Good user experience (UX) is quickly becoming a differentiating factor for websites and software alike. With so many options available, users aren't incentivized to use your system when there's something else out that that’s easier to use. But UX principles don't just apply to software; your docs need to be well-designed as well. After all, what's more frustrating than going to the help only to discover that you can't find the help you need? Use these 7 techniques to find out what your users need and to put best UX practices into effect for your documentation.
Improve Accessibility
This is a UX principle that’s often overlooked, but it's important to your users. Although the set of your users who have physical, mental, or learning disabilities may be smaller than the set of users without them, that doesn't make them a small percentage by any means, and it certainly doesn’t make them insignificant. For these people, accessibility features are the difference between using your software and throwing it into the pile with the others that didn't take their basic needs into consideration.
Practical UX Methods has some great information about how to apply accessibility features to software, but how do these principles apply to your documentation? A deep-dive on the topic is outside the scope of this article, but as a crash course, think of what readers with disabilities need from the material to use it.
To accommodate visually impaired users, use strong color contrast, larger font sizes, and alt text on images. These things will make it easier for all users to interact with the material but are vital for users with low vision. Additionally, work to make your help images understandable even without color – no “green circle means good outcome, red circle means bad outcome.” Colors can be helpful for users with normal vision but using a variety of icons can help those with colorblindness (including total colorblindness), and descriptive captions or alt-text will help users with no vision at all. Make sure your help works with screen readers.
Naturally accessibility features in your documentation should not stop with updates for users who are visually impaired. For users who are deaf or hard of hearing, make sure your help videos have subtitles or transcripts. For users with intellectual, cognitive, or developmental disabilities, carefully design your layout and navigation so it’s clear where the user is in the help and how to move about in it. Provide clear navigation links, as well as breadcrumbs to other pages. For users with limited mobility, make sure that navigation by keyboard alone (i.e., the tab button) is effective.
Again, this is not an exhaustive list of accessibility features you should include in your help—it’s a start. Do your own research on this point to make your help as accessible as possible.
Do a Clickstream Analysis
Clickstream analysis is a way of tracking your user's progress through a system to learn about where they go from one page to another. In software design, this helps you understand where your users stall out, where they get confused, and where they search for information.
In documentation, this kind of analysis not only helps you understand where they search for help in the system, but how they use the documentation itself. Use this technique to learn about where users go to find help topics, how they navigate from topic to topic, whether their search terms yield meaningful results, and so on. Even the most beautifully written help won’t cut it if the user can't find it; work with clickstream analysis with both your software and help system to find ways to help your users in the ways they're expecting to be helped.
Use Accepted Design Patterns
As I suggested above, there are ways users are accustomed to interacting with any given design element. These are called “accepted design patterns.” For example, it's become common that when you click in a date field, a calendar appears to help you select a date. (And I’ll bet that if the calendar doesn’t appear, it annoys you to manually enter a date.) Similarly, it’s become common to include a sort option on the headers of grids, so users can more easily find the row they want. These—and many other tiny interactions you see every day online—are accepted design patterns.
Accepted design patterns don’t only apply to software or web pages; you can also apply them to help. For example, the new user walk-through is a help design pattern that’s gaining traction within software. The use of breadcrumb links is also a well-used help design pattern that also makes your docs more accessible.
You can find several help patterns already cataloged on the UI Patterns website under Onboarding, and there are many others that can be converted from software or websites to online help. That said, your user community is unique. Dive into what they expect to see when they access your help so that you can provide a smoother, more intuitive experience.
Hold Consistency Inspections
Consistency inspections are a way for your designers and developers to ensure your users get a consistent experience. Practical UX puts it perfectly:
Consistency is a contract with the user promising that, once the user has learned a product’s functions and where to find them, these will remain consistent until the user completes their tasks. Breaking that contract without thoughtful consideration can decrease trust, increase user frustration, and diminish usability.
The help and documentation are the user's last line of defense against rage-quitting. If these assets aren’t consistent and clear, the users’ trust in the system may be irrevocably lost.
Documentation must be internally consistent, just like the software, but it's equally important that it’s consistent with the software itself. If the documentation tells you to click Send Now, but you can't find it anywhere on the page (because the button text was changed to Pay It Forward!), you're going to get frustrated fast. Having a style guide and rigorously adhering to it can help solve some situations, but not all of them. (That's not to say that style guides aren't important! But that's a discussion for another post.)
Situations like this are one of the reasons I advocate for regression testing the docs. If you can reduce your users’ pain while using your system—and increase their delight and joy—it’s good for your bottom line.
Do Content Audits
Like a consistency inspection, a content audit lets you confirm the information in the docs is still pertinent. In software or web design, this means confirming each screen still has value and connects with other screens. In the help, you have a similar goal: confirm the information is still good, that it still matches the system, and that there aren't dead-end topics with no links to additional information. Because of its overlap with consistency inspections, they’re good UX tasks to perform together.
The frequency of your content audits depends on how often your organization updates the software and the help. For example, if you have regular releases once or more per month, do a content audit on the help about once every six months. If you release new help once a quarter, a yearly check will help make sure your users are still getting the best experience.
Use “Every Page is Page One”
Every Page is Page One is a documentation technique created by Mark Baker. It’s designed to address the problem that you never know which order your users will want or need to interact with help topics. To solve this problem, assume that every page is the first page the user will encounter.
The idea is simple in theory but tricky in practice. After all, in the flow of writing it can be hard to remember that some of your audience will be introduced to this topic by the very article you’re writing. It’s also difficult to balance the needs of these users with the needs of those who are already familiar with the topic and only need a specific kind of help.
When considering this principle, look at how your organization reviews the docs and think about each topic like a Wikipedia article. Wikipedia is the ultimate experiment in how to address the Every Page Is Page One problem. After all, it’s possible for users to stumble on any given Wikipedia article from almost anywhere on the internet. If you find that your docs aren’t useful to new or introductory-level users, consider applying the three main tactics Wikipedia uses: introductory paragraphs that provide context, robust cross-linking, and detailed tables of contents.
Conduct User Testing
This is one of those topics I could rail on about for ages, but I'll keep it brief here. Give your docs a UAT. It’s easy to believe the technical writer is hired and paid to understand what the user needs and then deliver it. However, you could think of developers in the same way, and you would never think to release their work without testing or UAT.
Just like regression testing, docs UAT is crucial in ensuring that your users get the kind of help they need. Whether you do docs UAT alongside software UAT or separate from it, get the docs in front of your users and customers. You need to see how they interact with the docs, what they look for, and the problems they experience. This is similar to clickstream analysis, but user testing also involves carefully watching your users to gain insight about stumbling blocks and pain points.
One of the greatest insights of my career happened when I user tested my docs. I needed to create a quick guide a group of older users who were not very tech savvy. Many were extremely well-educated with master's and doctoral degrees, but they hadn't had much interaction with technology over their careers. Now, at the ages of 70 to 80, we weren’t likely to train them to interact naturally with a computer. The system design was mostly centered around our much larger audience of more tech-savvy users, so major UI changes weren't possible. Instead, it was on the docs to make sure these users understood how to do their jobs in the system.
I created a first pass guide, trying to bear my audience’s needs in mind, then I test drove it on my parents. I was careful not to help them; I just observed their behavior. I learned that no matter what help I employed, it needed to be seen on a second screen or physically printed to avoid users having to flip between the help screen and the work screen. I learned that my font was too small. I learned that I needed clearer indications about where to look for things on the screen. I learned that the bright primary colors I used to highlight screen elements were helpful, not insulting. I learned about how they searched for help on the page and where they got lost.
As a tech-savvy user, this quick guide feels crude to me. But I’m not its audience. Having user tested it, I’m confident this guide works for its audience. And that’s the point of all these techniques: to give our users the best help we can provide.
Don’t forget to grab your copy of the Docs Review Worksheet! Reviewing documentation can be a challenge. What feedback is important to pass along? Where do you even start?
This worksheet will walk you through the process of understanding your users, what they want and need, and where the docs do or don’t meet those needs. This sheet is great for technical writers, development teams, project teams - anyone who needs to review the docs.