This site uses cookies. By using our site, you agree to our Privacy and Cookie Policy
scroll

Tips for building contextual help in web applications

 

What is Contextual Help and Documentation?

Contextual Help is an action given to provide assistance. It is integrated inside a product without the need to read the full documentation. Contextual Help can be seen in tooltips, pop-ups, dialogs, and side panels. It is great for guiding users on what a specific feature does or what a field means.

Documentation is an extensive, descriptive text provided to users when they seek a piece of advice or want to learn about specific parts of the product or service. It is usually made available via help center pages or support pages. 

Help and documentation are ranked 10th in the list of 10 usability heuristics. It is not only an indicator of good design but for some users, having the means to ask for help and quickly find said help can be crucial.

Who are the main users?

New users

First-time, new users who are not familiar with an interface and need assistance. For this purpose, one of the best ways to assist users is to provide onboarding tutorials. 

New and experienced users

Onboarding is also a good way to update users when the product was redesigned or some features or options were updated. 

Users who need to recall

Users who quickly want to look up a particular fact about the product or when they cannot remember it at the present moment.

Users who need recover 

Users who want to find out what went wrong when there is an issue or a problem.

Users who need assistance

Users who cannot complete specific actions or tasks.

Users who want to become experts 

Users who want to gain proficiency in the product.

Contextual help in tooltips

A tooltip is a small rectangular overlay that provides brief information related to the content. Tooltips are triggered when users hover their cursor over a link, an icon, or an image. Tooltips can be text-based or graphic-based. The Lucidchart intelligent diagramming tool has both types of tooltips.
Lucidchart Text tooltip

Lucidchart. Text tooltip.

Lucidchart - Graphic tooltip

Lucidchart. Graphic tooltip.

Benefits

  • Easily triggered

Drawbacks

  • Distracting (especially for those users who are familiar with the product)

Contextual help in pop-ups and dialogs

Contextual help in pop-ups presented as short, informative text. It can include graphics and tutorials. 

Figma provides a good example of an onboarding tutorial in a pop-up dialog. Users can interact with the content by switching tutorials or navigating to an external page by clicking More.

Figma - Tutorial pop-up

Figma. Tutorial pop-up.

Adobe offers a tutorial in the dialog that pops up right after logging in. It’s a quick and easy way to suggest other options to users.
Adobe - Tips demonstration in a dialog

Adobe. Tips demonstration in a dialog.

Pop-up dialogs can be more complex, especially when you need to put more information in one place. Information in them is split into chunks and corresponding lists. It can be revealed when a specific icon or button is pressed. Gmail displays quick start guides and help in a dialog box. It provides access to the help forum and all related articles. A nice bonus is that the dialog can be dragged to help reduce content overlapping.

Gmail - Draggable dialog

Gmail. Draggable dialog.

Although I enjoy using Figma and it's my primary design tool, I think links inside a pop-up could be designed more clearly. After clicking on one of the links, most of them unexpectedly would take you to an external source. 

Gmail, in comparison, clearly indicates which link would open an external page and what information will be revealed in the dialog. 
Gmail and Figma - behavior with External links

To give credit, Figma offers fantastic documentation about keyboard shortcuts. It is integrated into the tool and opens up like a console panel.

Figma - Keyboard shortcuts

Figma. Keyboard shortcuts.

Benefits

  • High visibility 
  • Reachable within one click 

Drawbacks

  • Overlaps the content
  • Blocks user actions until dismissed

Contextual help in side panels

Contextual help in side panels can contain more information because of its size. They include video tutorials and training modules, graphics, information on featured options, search, and links to help pages. But it comes with its benefits and drawbacks. For example, on the Monday tool, the Help section takes up a large portion of the screen and the content. For some users, it can be distracting and overwhelming.

Monday - Help integrated into a side panel

Monday. Help integrated into a side panel.

Outlook also provides a good example. Help is integrated into a side panel that moves the content to the left. The content adjusts to the new width, and all the information stays in focus.

Outlook - Help in a side panel

Outlook. Help in a side panel.

Benefits

  • Well structured
  • Include more detailed information

Drawbacks

  • Can be too heavy and overwhelming 
  • Can block visibility

Help pages and documentation

Help pages contain more detailed information and cover many topics. Technical documentation, feedback section, FAQ, and support are all parts of Help pages. The information is divided into categories. 

Help pages consist of related elements grouped together and that display a visual hierarchy. Good Help is easy to find without distraction. And good documentation is written in simple and concise language to provide quick search results.

Material Design is a great example of technical documentation. It is comprehensive and detailed. The information is divided into blocks, the text is descriptive, and it contains graphic elements.

Material Design guidelines

Material Design guidelines.

Another positive example is the Facebook Help Center. It is easy to navigate and all the information is stored in one place.

Facebook Help Center - Material Design

 

In comparison, the Google Help Center is too cluttered with information, categories, and filled with link buttons that take you to other parts of the documentation. It's easy to lose focus and get overwhelmed with information.

Benefits

  • Well structured
  • Include detailed information

Drawbacks

  • Time-consuming. It’s easy to lose track of time 
  • Can distract from the main purpose
  • Can be too loaded with information

Summary

Users may be reluctant to refer to documentation for various reasons: 

  • documentation may be boring and difficult to understand; 
  • it is time-consuming; 
  • users may feel lazy and prefer alternatives.

Yet, it’s still important to provide users with help and documentation when they need it.

To create good contextual help, information should be divided into categories, showing a clear visual hierarchy, and highlighting keywords. Help should contain search capabilities and be complemented by graphics and videos. It should be written in plain language, troubleshoot, and help users recover.

In case you need help, advice, or consultation on building and providing Contextual Help, our specialists will be happy to help you.

by Olena Shevchenko, Senior UI/UX Developer
March 30, 2022

Related articles

Building user web interfaces with React
by Svitla Team
July 21, 2021
article
article

Let's meet Svitla

We look forward to sharing our expertise, consulting you about your product idea, or helping you find the right solution for an existing project.

Thank you! We will contact very shortly.

Your message is received. Svitla's sales manager of your region will contact you to discuss how we could be helpful.