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.
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.
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.
A broader summary or additional explanation paired with headers to describe the subject or task of the page in further detail.
An explanation for a triggered validation error displayed below the form field.
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.
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.
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.
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.
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.
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 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.
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."