Download a free poster of Jakob’s Usability Heuristic #10 at the bottom of this article.

The 10th usability heuristic states:

Even though it is better if the system can be used without documentation, it may be necessary to provide help and documentation. Any such information should be easy to search, focused on the user’s task, list concrete steps to be carried out, and not be too large.

Websites and applications can offer two types of help: proactive and reactive. Proactive help is provided before the user has encountered a problem, in order to prevent issues. It includes onboarding tutorials and contextual tips. In contrast, reactive help includes materials such as documentation, videos, or even tutorials for those situations when users have an issue and they seek out advice to address it.  (Even though some users may consume such materials proactively, it is rare that they do so.)

The two types of interface help are proactive and reactive. Proactive help can be further divided into two categories of push and pull revelations.
The two types of interface help are proactive and reactive. Proactive help can be further divided into push and pull revelations.

Proactive Help

The goal of proactive help is to familiarize users with an interface. Proactive help often occurs in three scenarios:

  1. New users at first launch of an interface
  2. Novice users as they gain proficiency with an interface (this happens over time and is most relevant for complex applications)
  3. Existing users encountering a new or redesigned interface

Proactive help can be implemented through tutorials, instructional overlays, templates, contextual help, tooltips, and wizards.

Asana offered several templates to help users get started with common project types.
Asana offered several templates to help users get started with common project types. Templates can be useful for both new and existing users.

Push and Pull Revelations: Two Types of Proactive Help

Proactive help comes in two forms, push revelations and pull revelations. The difference between these relies on whether they are individualized to the user’s context and likely to be related to the current user goal.

Push revelations occur when an interface provides assistance or help content that isn’t relevant to the users’ goals.  Aptly named, this type of proactive help pushes help content in a relatively random way, with no regard for what the user is trying to do at the moment. The classic example is the tips or instructional overlays that occur when an application is launched and that inform users of new features.

O'Reilly pushed proactive help with an instructional overlay
When logging into O’Reilly, a digital library, the system pushed proactive help with an instructional overlay highlighting interface elements.

Push revelations are often ignored by users because they get in the way: people want to use the interface, not just read about it. This type of help also lacks context, as it’s challenging to remember the pushed information when it is not related to your immediate goals.

AddEvent pushed a tutorial on new users
AddEvent, a calendar event tool, prompted new users with an option to view a tutorial of the interface. This push revelation was appropriately paired with the option to skip the tutorial. However, even if users  engaged with the tutorial, they would discover that it was too basic! Instructions to create an event are likely unnecessary because the system follows design standards and is aligned with traditional mental models of how to create a calendar event. Interfaces that provide basic information as proactive help are partly why users skip push revelations. When users engage with them and are shown obvious commands and controls, they may start to perceive all push revelations as low value and not worth engaging with.

Pull revelations show contextual tips that are relevant to the user’s task. They could appear when the mouse is near corresponding controls or when the user has started a corresponding flow. Implementation methods include tooltips, contextual overlays, or wizards. Pull revelations are less likely to be ignored because they provide timely information to help users accomplish a task.

Microsoft provided valuable help content through a pull revelation
Microsoft Word recognized that the user was working on a resume and provided a tip to See resume suggestions from LinkedIn. This is an example of a pull revelation, because it is triggered by the individual user’s behavior, not ‘pushed’ to all users.

Guidance for Providing Proactive Help

Keep proactive help short and to the point. Proactive help distracts users from their core task, so it’s important that the help is timely, informative, and relevant. Write the content from the user’s perspective and consider using verb-oriented phrases.

Favor pull over push revelations. Make help content accessible, but don’t force users into it.  Use push revelations for information that is likely to be needed regardless of context and pull revelations to provide timely help content relevant to the user’s task.

Dovetail provided timely help content
Dovetail, a user research platform, provided timely help content when users opened a data page — a pull revelation. This was a better choice than presenting this content as a push revelation (e.g., at login).   ​​​​​

Push revelations should be easy to ignore (e.g., by dismissing them). Push revelations stall users from accessing the core interface. Additionally, push revelations can frustrate users that are already familiar with the interface or don’t feel they need help. Anytime you present content in this way, make sure users can skip it.

MindNode pushed a tutorial for first-time users, but allowed them to skip it
MindNode, a visual-mapping mobile app, launched a tutorial for first-time users (a push revelation) and offered an option to skip the tutorial.

Proactive help content should be accessible elsewhere. After engaging and exploring an interface on their own, some users may remember having seen a push revelation that was relevant but that they ignored at the time. This situation is common in complex-application domains. Allow these users to access proactive help content by linking to it from the application’s or site’s UI.

iOS provided tips in the form of push and pull revelations, depending on the context
iOS provided help content (labeled Tips) for interface and system changes. These tips were presented as proactive help (both pull and push revelations depending on the context), but could also be accessed in the iOS Tips app (which is preloaded on iPhones).

Reactive Help

Reactive help is provided in response to the user encountering a problem. The goal of reactive help is to answer questions, troubleshoot user problems, or provide detailed documentation and materials for people who want to become expert users. Reactive help comes as frequently asked questions, technical documentation or tutorials, or training modules.

Guidance for Providing Reactive Help

Ensure reactive-help documentation is comprehensive and detailed. Don’t include only obvious information. If users are looking at your FAQs, training manuals, system documentation, or anything similar, they are not doing it for fun. They need help with something and likely want detailed instructions. Documentation like this should not solely provide high-level overviews, though that content is warranted at the top of the page.

Material design provided expansive technical documentation
Material Design provided expansive technical documentation which provided insight on various components, what they are, and how they’re used.
Microsoft’s Mixed Reality Toolkit documentation was sometimes vague and did not provide descriptions of mentioned designs. In this case, the documentation mentioned visual cues like ‘proximity light’ and ‘compressing cage’ but failed to define these patterns, how they could be implemented, or link to further details.
Microsoft’s Mixed Reality Toolkit documentation was sometimes vague and did not provide descriptions of mentioned designs. In this case, the documentation mentioned visual cues like ‘proximity light’ and ‘compressing cage’ but failed to define these patterns, how they could be implemented, or link to further details.

Support scanning by using the rules of writing for the web. Chunk content, create a clear visual hierarchy, highlight keywords, and use bulleted or numbered lists. When users get to your help pages, they might be in a rush to solve a problem. Even if they’re just browsing, reading your content isn’t the main priority— they want the information they are interested in.

Figma's support pages were easy to scan with clear visual hierarchy
The support pages for Figma, a prototyping tool, were easy to scan: they had clear headings and numbered lists.
The Birds of Northern Europe iOS app had support pages that were difficult to scan
The support pages for Birds of Northern Europe, an iOS app, were hard to scan. Instructions were written in paragraph form rather than numbered lists.

Consider using graphics and videos as a secondary information source. For complex interactions, visual methods can help users better understand and mimic instructions. Still offer text-based help, as people aren’t always able to (or want to) watch videos.

Oculus offered video and text-based instructions
Oculus provided video and text-based instructions on how to set up virtual-reality boundaries.
Dyson failed to provide text instructions in addition to video tutorials
Dyson failed to provide text instructions in addition to video tutorials. Though captions are available in the video, listing the instructions on the page would increase visibility of the content and decrease the interaction cost.

Optimize for search. When users need immediate help for a specific issue, they need a tool to find it fast. Ensure that your search capabilities are fully functional and provide relevant results.

TeamDesk offered relevant documentation for search results
Teamdesk, an online database, provided relevant documentation search results and supported scanning by highlighting the search keyword throughout the results listing page.

 

Netvue lacked a search feature in their documentation
The Support page for Netvue, a surveillance-camera manufacturer, had no visible search box.

Group help topics into relevant categories. Users may come to your documentation looking for certain types of help which could revolve around experience level or particular topics. Help users identify content that meets their needs by categorizing your offerings.

Xbox offered categories for their support documentation
Xbox provided help categories (or sections) on its support page.
The AirBrush app did not categorize it's help content
AirBrush, an iOS photo-editing app, offered GIF tutorials but failed to offer any categorization. The app provided 20+ GIF tutorials in a single-scroll view with no titles or groupings.

Highlight top content that is frequently viewed. If you have a lot of support and help content, assist your users in finding content they need by highlighting relevant aspects. For instance, you might highlight popular articles or training modules with high social proof (like highly recommended or most viewed).

Nintendo's support pages recommended top articles
For various support categories, Nintendo provided a list of top articles.

Conclusion

Help and documentation are an important element of user experience. They are often necessary, but rarely fun. In general, users don’t like to read, and they particularly don’t like to read instructions. But any kind of trouble in the interaction is also a learning opportunity for the user and thus an opportunity for the designer to impact information and grow the user’s mental model in ways that would not have happened without the impetus of this trouble. Anticipate when your users will need help and provide relevant information that will support them in accomplishing their goal. Supplement your proactive help with a documentation repository that users can refer to as needed. And remember to keep help content brief, to the point, and easy to scan.