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.

When to use a link to documentation

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.

For linking to documentation from the GitLab app, see linking to /help.

Link text

In most cases, phrase the link as a question.

• Example: A merge request approval is required. Who can approve?

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.

• Example: Approve a merge request. Learn more.

Note: The punctuation is not part of the link.

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

External links

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.

• Example: Learn how to use minikube in the Kubernetes documentation .

Help icon

If link text is not possible and space is tight, use the outlined question 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.

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

When a user needs to reference extra information to complete a task, choose the surface based on how the user will use it:

• If required to complete the task, show the content inline or use another pattern.
• If optional, short, or dismissed when the task is complete, use a drawer.
• If optional, rich assistance, or persists when the task is complete, use an application panel.

When to use a drawer

• The information is supplemental, not critical to completing the task, and the user references it while working in the UI.
• The content is too long for a tooltip or popover but short enough to comfortably read in the drawer.

When not to use a drawer

• The help is a necessary part of completing a specific task: use a modal instead.
• The content is short enough for a popover: use a popover instead.
• The content is too long to read comfortably in a drawer: link to the documentation instead.

Content guidelines

• Relate drawer content to a specific context or task, and reflect that context in the drawer header.
• Store drawer content as Markdown in the GitLab repository /doc directory, not hard-coded in the product. Follow the documentation topic types guidelines and the general drawer content guidelines.
• Collaborate with a technical writer when defining the content. Their review is required on related merge requests.
• Link to documentation sparingly. If needed, add a single link at the end so users can learn more.
• Avoid action buttons in reference drawers. The underlying page keeps its own actions available, so help drawers focus on reference information that supplements them.
• Help drawer content doesn't need to be localized.

TODO:

Add a live example. Create an issue

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.