On this page

Key UX Concepts

Help and content ramp

The objective of the help system is to provide instructional content that answers these common user questions:

  • What is this?

  • Why do I care?

  • How do I make the right decision?

These questions can apply to an entire page, to a specific section, or to a specific element.

The help system is also a content strategy to help users make smart decisions without overloading them with information. It provides a content ramp that progressively discloses more information as users need it. It is not simply about using the help panel. The system starts with the UI text on the page and eventually leads to external documentation. Another way to think of the content ramp is in terms of sizes or steps up the ramp, as it increases in both the depth of information and user’s required attention.

Small (bites)

The first step of the ramp is UI text on the page, which requires minimal effort for the user to read and act upon. This includes all the text on the page such as headers, descriptions, form field labels, placeholder text, and constraint text.

A
A
A
B
B
B
D
C

A.
Headers

The header for the page and sections, as well as labels for form fields and key-value pairs. Headers explain the subject or task in a concise manner.

B.
Descriptions

A broader summary or additional explanation paired with headers to describe the subject or task of the page in further detail.

C.
Input placeholders

An example that help users make decisions for an input.

D.
Form field constraint text

A line of text, below an input, explaining requirements and constraints of the form control.

E.
Form field error text (not shown)

An explanation for a triggered validation error displayed below the form field.

Medium (snack)

The second step of the ramp is content in the help panel, which extends the UI text on the page. The help panel content provides information that helps users understand concepts more fully, make good decisions, and complete tasks quickly without leaving the console for external information. This step is explicitly organized to focus on either the page, a specific section, or a specific element.

A
A
A
B

A.
Info links

  • Info links are the triggers that opens the help panel and display the corresponding content.

  • An info link should always be anchored to headers.

B.
Help panel

  • An extension to the UI text on the page. Aside from answering the 3 main user questions ("What is this?", "Why do I care?" and, "How do I make the right decision?"), the help panel should have in-depth information to answer additional questions such as:

    • What do I need to do before starting the task?

    • What will the task accomplish?

    • Why is the task required? If the task is optional, how do I decide if I should do it?

    • What are the consequences of certain decisions (cost or otherwise)?

    • Why is a form field required? If a form field is optional, how do I decide if I should do it?

    • How do I decide which values to choose from a form field?

  • Display page-level content as the default in the help panel.

  • The content should change when the user has either triggered an info link on the page or navigated to a new page.

  • When the user closes the help panel and later reopens it within the same page view, the content should remain the same as what was previously shown. The content should not automatically switch back to the default content.

Large (meal)

The third step of the ramp is in-depth documentation or related resources. These sources of information should typically be service documentation that navigate the user to a new tab.

A
B

A.
Learn more links - optional

  • External links to relevant service documentation. These links may be used with information in transitional elements like alerts, flashes, and modals.

  • If a content ramp with the help panel cannot be implemented, stand-alone learn more links may be used as a fallback. These links should be placed after descriptions.

B.
Learn more footer

  • A list of links at the bottom of the help panel that go to relevant help topics in the service documentation.

  • The links may go to other content, such as pricing pages or support pages, when absolutely necessary.

  • In multipage create flows, provide links that go to the corresponding procedure or set of procedures in the service documentation.

General guidelines

Do

  • When using the help panel, display page-level content as the default help panel content.
  • When using the help panel, always include a page-level info link, even if it is the only one available on the page.
  • When using a help panel in a multistep create flow, include the help panel in every step.
  • Always place info links next to the appropriate header rather than descriptions or other elements.
  • Always make the header of the help panel consistent with the header of the corresponding page, section, or element. This provides a quick reference point between the content on the page and the help panel.
  • Learn more links must always navigate the user to the resource in a new tab.

Don't

  • Don’t include a help panel on a service homepage.
  • Don’t use the stand-alone learn more links on pages that also have help panel content unless the link is used within a transitional alert, flash, or modal.
  • Don’t include an empty panel on the page if there is no content for the help panel.

Writing guidelines

General writing guidelines

  • Keep labels and descriptions clear and concise.

  • Use parallel sentence structure.

  • Use sentence case for all text. Don't use title case.

  • Use present-tense verbs and active voice wherever possible.

  • Don't use "please," "thank you," or Latinisms such as "e.g.," "i.e.," or "etc."

Page headers

Container headers and descriptions

Follow the writing guidelines for headers.

Form field labels and description

Follow the writing guidelines for form fields.

Input placeholders

Follow the writing guidelines for inputs.

Constraint text

Follow the writing guidelines for form fields.

Info links

Follow the writing guidelines for info links.

Accessibility guidelines

General accessibility guidelines

  • Follow the guidelines on alternative text and Accessible Rich Internet Applications (ARIA) regions for each component.

  • Make sure to define ARIA labels aligned with the language context of your application.

  • Don't add unnecessary markup for roles and landmarks. Follow the guidelines for each component.

  • Provide keyboard functionality to all available content in a logical and predictable order. The flow of information should make sense.

  • Make sure you define ARIA labels for the selection inputs that are aligned with the language context of your application.

Links

Follow the accessibility guidelines for links.

Help panel

Follow the accessibility guidelines for help panel.