Bring Your Help Docs into Your UX Design

Key Takeaways

Incorporating the development of help information during the UX design process can lead to more effective, context-specific help that users actually use. This approach considers the user experience rather than just documenting features and can help avoid unnecessary help content that users may not need.
Involving the content writer early in the UX design process can help identify potential user issues and develop language and vocabulary standards across the product. This can lead to more user-centric help and streamline the help-creation workload.
While product documentation is necessary, it should not be the primary source of user help. Instead, help content should be user-centric, addressing specific user issues in context, and should be part of the UX test. Marketing communications, not self-help sites, should be used to promote product features.

When do you usually develop FAQs or self-help content for your product? For most startups I’ve worked with, the answer is “just before launch.” That seems patently sensible, doesn’t it? By that time, you’ve nailed down exactly what the product is, what it does, and who it’s for. On the surface this seems like the perfect time to then throw together a few likely FAQs, perhaps around questions that have arisen out of your user testing. Or is it? I’ve found that the best way to create help information is during the development of the user experience. After all, your support is part of

that experience, right? If you make self-help part of the UX design, you can:

avoid wasting time writing help no one ever has a need to read
avoid “documenting features” for the sake of it
link help to the points at which users actually need it
develop context-specific help that users actually use — and appreciate.

I’m guessing you’ll agree, in principle, that a user-centric approach to help is a good idea. Yet many product managers, owners and developers want to document processes or features end-to-end. The thing is, users don’t often struggle with a whole process, end-to-end. If they do, you have bigger UX issues to address. More commonly, there’ll be specific sticking points in the process where the user is confused, usually around ideas or tasks the users are unfamiliar with, or aren’t expecting. User-centric help lets you address those elements directly and specifically, in situ. It allows you to get users who actually need assistance to your self-help right from within your app or product, because you’ll have created targeted help that’s worth linking to from key points in the interface, like error messages or feature tours. And it also helps cut down your help-creation workload. The alternative to user-centric self-help is to guess: to provide more general content (since you don’t know when in the user experience users will access it) and hope they wade through it to find the stuff they need. This is less than ideal, and less than useful. Help like this sees helpdesk costs increase. So let’s see how hard — or easy — it is to develop user-centric help.

A process for developing user-centric help

To create user-centric help, you need to get your writer (or the person who’ll be creating your self-help content) involved early in the UX design process, before user testing begins. They’ll be able to help identify potential sticking points in interactions, and provide verbiage that effectively provides users with doorways to help — calls to action, if you will. Depending on your app, that text could take the form of:

links
tooltips
error messages
tour content

…and more. The point is that the writer and UX designer are looking at the experience, not the feature. They’re considering user flows from a use-case perspective, not a pure process perspective. As an example, a product I was working on depended on Java, and users on different systems received a range of different errors from Java itself, and from our app interacting with Java, depending on whether their version of Java was current. So we preempted their confusion with a simple link from the relevant error messages in our app to a help page that showed how to solve that immediate problem in situ, by updating their version of Java. We wrote a separate piece of help content that showed users how to check that their version of Java was up to date, and to update it if it wasn’t. You might think that help page could do the job of both, but it didn’t. While this second piece was helpful, it was less helpful than the first for people in this use case, because it assumed no context. The first piece, on the other hand, helped users get over the immediate technical hurdle, and continue on to complete the task they’d already started. That’s the value of user-centric help. Involving the writer during the UX design process also ensures that language and vocabulary standards and styles can be developed and maintained across your product. This, along with visual styles, supports the users’ understanding of what outcomes they’re generating as they interact with your product. The next step is, of course, to test and refine the interfaces — again, as a team. This way, the writer becomes part of the UX process, responding to user feedback via the interfaces and the help pages they link to. But, importantly, with this approach, the help content becomes part of the UX test. After all, whether or not a user can independently achieve their objective with your product may ultimately come down to the usability of your self-help.

Common objections

Let’s wrap up with a few of the most common objections I hear to this approach to self-help.

But where will our product documentation be?

If you want product documentation, make it. Just don’t call it user help, or make it users’ first port of call on your self-help site.

But how will users get an overview of the whole process?

There are definitely cases where users will want an overview of a process, as in the example I mentioned above. But it’s important to know where to draw the line. In the example above, a user who receives Java errors may stop doing what they’re doing, ignore the in-app help link, and go to the support site to search for something like “Java error.” Of course, you don’t want to only offer self-help content that assumes they’re in the middle of a specific procedure within your app. You want to give them a solution that will work outside of very specific use-cases, too, and in this instance, that required a step-by-step how-to. What we didn’t do, though, was document every error the user may or may not receive from our app. Again, providing useful self-help is about knowing where to draw the line.

But how will we tell everyone about these great features?

This isn’t what your self-help site is for. There’s no point documenting the nuances of every element of your new feature just for the sake of your ego. Instead, document what needs to be documented as user-centric information that can be delivered in appropriate parcels as and when it’s needed. And save the hype for your marketing communications.

Frequently Asked Questions on UX Design Documentation

What are the key elements to include in UX design documentation?

UX design documentation should include several key elements to ensure it is comprehensive and useful. Firstly, it should include a project overview, outlining the project’s goals, target audience, and key stakeholders. Secondly, it should include user personas, which are fictional representations of your target users. Thirdly, it should include user flows, which are visual representations of the user’s journey through your product. Fourthly, it should include wireframes, which are low-fidelity representations of your product’s layout. Lastly, it should include prototypes, which are interactive mockups of your product.

How can I make my UX design documentation more user-friendly?

To make your UX design documentation more user-friendly, consider using visual elements such as diagrams, flowcharts, and screenshots. These can help to break up large blocks of text and make the information more digestible. Additionally, use clear, concise language and avoid jargon where possible. It’s also helpful to include a table of contents at the beginning of the document to help users navigate the information.

What tools can I use to create UX design documentation?

There are many tools available to help you create UX design documentation. These include wireframing and prototyping tools like Sketch, Figma, and Adobe XD, as well as documentation tools like Confluence and Google Docs. Additionally, tools like Miro can be used for creating user flows and journey maps.

How often should UX design documentation be updated?

UX design documentation should be updated regularly to reflect changes in the product, user feedback, and new insights from user research. This ensures that the documentation remains relevant and useful for all stakeholders.

How can I ensure my UX design documentation is effective?

To ensure your UX design documentation is effective, it’s important to involve all relevant stakeholders in the process. This includes not only designers and developers, but also product managers, marketers, and even users. By involving all stakeholders, you can ensure that the documentation meets everyone’s needs and expectations.

What is the role of UX design documentation in the design process?

UX design documentation plays a crucial role in the design process. It serves as a reference point for all stakeholders, helping to ensure everyone is on the same page about the product’s design and functionality. It also helps to facilitate communication and collaboration between different teams and departments.

How detailed should UX design documentation be?

The level of detail in UX design documentation can vary depending on the project and the audience. However, it’s generally best to include as much detail as possible to ensure all stakeholders have a clear understanding of the product’s design and functionality.

Can UX design documentation help with user testing?

Yes, UX design documentation can be a valuable tool in user testing. It can help to identify potential issues and areas for improvement, and it can also serve as a reference point for testers.

How can I make my UX design documentation more engaging?

To make your UX design documentation more engaging, consider using storytelling techniques. This could involve presenting the information in a narrative format, using case studies or examples, or incorporating visuals and interactive elements.

What are some common mistakes to avoid when creating UX design documentation?

Some common mistakes to avoid when creating UX design documentation include neglecting to involve all stakeholders in the process, failing to update the documentation regularly, and using jargon or overly technical language. It’s also important to avoid making the documentation too lengthy or complex, as this can make it difficult for users to understand and use.