Contextual help and info

The UI should be self-explanatory. If extra help is required, it should be in the UI itself, as either UI text or as text within a drawer.

Affordance is higher when help content is available in context.

Documentation can change, and links from the UI to the documentation can become out-of-date or circular. You should avoid links from the UI to the documentation if you can.

However, you can link from the UI to the docs if:

  • Users require information that can't be communicated in the available space. (For example, a list of variables that are defined fully in the documentation.)
  • To use the feature, users need to understand a concept in more detail.
  • The UI is part of a larger workflow.

Formatting help content

Help links open in a new tab to ensure:

  • The result of clicking links is predictable.
  • The user does not need to navigate away from their task.

To learn how to link to GitLab documentation in various programming languages, see Linking to /help.

In most cases, phrase the link as a question.

If you can't determine a useful question, use Learn more. However, be aware that Learn more is not descriptive or meaningful, and should be used sparingly.

Note: The punctuation is not part of the link.

For screen reader users, add an aria-label with a full-sentence description.

When linking to the GitLab documentation, don't add the external link icon. Even though documentation links on GitLab.com take the user to docs.gitlab.com, the same links on self-managed open in the instance's /help.

When linking to third-party documentation, outside the GitLab instance, make that clear in the link text and use the external link icon. The icon should use aria-label="(external link)", or similar, to communicate the purpose to screen reader users.

Help icon

If link text is not possible and space is tight, use the help icon that, when hovered or focused on, shows the summary in a popover. The popover title should be the question that is answered by the summary. A Learn more link can be added to the popover to associate additional, relevant information.

DoDon't
Use the outlined question-o.svg icon in $blue-600 (#1068bf)
Use the solid icon question.svg or a color other than blue
Popover with link to documentation
Show information in the popover with a link to documentation
Popover with link to documentation
Use the icon as a link or with a tooltip

Info icon

There are exceptions when an info icon is used instead of the help icon. While the help icon unblocks a user by answering a question, the info icon provides additional details about the current context.

Providing reference information

In some cases users might need to reference additional information for completing a task in the UI. When the content length allows, we can surface such information using the drawer component.

When to use a drawer

  • When the help information is supplemental and not critical to the completion of a task.
  • When we expect the user to reference that information while performing tasks in the UI.
  • When the content is too long to show in a tooltip or popover.
  • When the content is short enough to comfortably read in the drawer.

When not to use a drawer

  • When help content is a necessary part of the flow for completing a specific task, consider using a modal instead.
  • When help content is short enough, consider using a popover.
  • When help content is too long to be easily read in a drawer, consider linking to the documentation instead.

Content guidelines

  • Drawer content should always be related to a specific context or task in the UI. The drawer header should reflect the context or task the user is performing.
  • Drawer content is stored as Markdown in the GitLab repository /doc directory, rather than hard-coded in the product code.
  • When writing drawer content, use the documentation topic types guidelines and general drawer content guidelines.
  • You should collaborate with a technical writer when defining the content, and a technical writer review is required on related merge requests.
TODO:
Add a live example. Create an issue

Linking to documentation in a drawer

Links to the documentation should be used sparingly since our goal is to present the necessary reference information in the UI. If you need to link to additional documentation, add one link at the end of the drawer content so users can learn more if they found the drawer content insufficient.

Using actions in reference information drawers

It's not recommended to use action buttons in drawers in conjunction with reference information since the page the drawer is on might have its own set of actions that remain accessible when the drawer is open. Drawers with help content should focus on providing reference information that supplements the interactive actions in the UI.

Localization of drawer content

It's not required to localize the help drawer content.

Behavior

For general guidelines follow the drawer behavior documentation.

  • The trigger that opens the drawer should be specific to the content it contains. For example, a "Syntax options" link opens a drawer with syntax options documentation.
  • Both text and icon buttons can be used as the drawer trigger depending on the context. In either case it should be clear from the visible text or aria-label (for icons) that help will be provided.

Last updated at: