Contextual Help
Search the component library

Contextual Help

v1.0.0

Presents help and support articles within the product experience so that users can answer their questions without the interruption of opening a separate help system in a new tab.

Usage Guidelines

Every URL in the Next Gen platform should use the Contextual Help component, at a minimum configuring the two default items in the Help List.

Features

  • Answer user questions without leaving the product experience
  • Present articles based on the user's current location
  • In-page triggers can jump directly to relevant article
  • Fully responsive and accessible

Help List

Displays a listing of help articles relevant to the current url. Every url in the next gen platform should offer a Help List through this component. Common functionality includes:

  • Universal access through the Header
  • Standard location of 'Contact Support' information
  • Articles relevant to the user's current location and role

Selecting an article opens it within a detail view in the drawer.

Initially the drawer presents a list of contextual help and support articles for the page.

Selecting an article navigates into it, presenting the full content.

Standalone Articles

In situations where a feature or tool only appears on a url under certain conditions any related help content should be documented with a Standalone Article. This presents just the relevant article, without access to the overall Help List.

  • Standalone Articles must be accessed exclusively through Embedded Activation, described below.
  • Standalone Articles must not appear in the Help List.

Example standalone article. Note there is not an option to go back to the overall Help List from here.

Embedded Activation

Selecting the "Help" link in the App Header will open the Help List. You can also navigate directly to an article (either a standalone article or one from the list) through embedded activation.

A Help icon or a "Learn more" link can be used to activate an article from within the page. These should be positioned near the relevant portion of the page. Avoid mixing and matching both styles in the same page.

Two examples of controls that can be embedded in the page. Normally you wouldn't mix and match the two styles like this.

Article Features

Accordions

Content may be grouped into accordions which help organize and condense information. See the Authoring Guidelines below for details on how to include an accordion in your article.

Info Boxes

Authors may use info boxes to call attention to important information.

Example of accordions.

General Tip and Important boxes.

Authoring Guidelines

Use these guidelines when authoring articles for the Contextual Help component. If you’re using MadCap Flare to author articles, see these specifics for preparing Flare files.

Do

  • Write articles at the 9th grade reading level. If you like, use the Spelling and Grammar feature in MS Word. Click Spelling and Grammar and under Options, select "Show readability statistics".
  • Title articles in the form of a question. Contact Us and Popular Resources are an exception to this guideline.
  • List the 'Contact Us' article at the bottom of the Help List. The Contact Us article is single sourced across all products adopting the contextual help component. Authors can find the Contact Us file in the SVN o-help directory: o-help-content/EN-US/ContactSupport.html
  • List Popular Student Resources and Popular Instructor Resources articles in the second to last position of the Help List.
  • Use Online Help Google Analytics and tech support data to determine what info to include in articles. Work with Mark Giardina and Matt Norris to request KB metrics and usage reports. Be sure to also take advantage of the Snapshot Tool.
  • Include accordions when necessary to improve readability of longer topics or procedures. Consider using them as a replacement for "See this help topic" links.
  • Link to external assets such as EI guides, Marketing PDFs, Videos, etc. from within the Popular Resources articles when relevant.
  • Add Help List articles that are role specific (educator/learner/TA).
  • List up to 5 custom articles at the top of the list. These should be specifically relevant to features/tools accessible at the current URL. If the feature/tool is only available under certain conditions it must be documented in a Standalone Article instead.
  • Follow the formatting guidelines below.

Don't

  • Reformat the layout or structure of Popular Resources and Contact Us article types. Your UA Design representative on the UXF Team will work with you in reviewing recommendations to ensure standardized contextual help articles are uniform across the customer experience.
  • Link to other articles in the contextual help component.
  • Include tables.
  • Exceed more than 7 articles per page (5 custom, 2 default: Contact Support and Popular Resources).
  • Include articles about features/tools which aren't permanently accessible from the current URL in the Help List. (Use standalone articles instead.)
  • Link out to Pearson Support KB articles.
  • Link out to Online Help Systems.

Formatting guidelines

After you’ve committed your contextual help files to SVN, a sanitization script runs to clean the source html files to follow the tag conventions established by the UX framework.

Sanitization
The sanitization script alleviates authors from having to worry about the details of code and html tags used in their help files. Headings, sub-headings, body copy, bold and italics, lists and unordered lists, etc. are all reviewed and cleaned by the sanitization script to follow the same html semantics as other components. Sanitization also helps to ensure we are following accessibility best practices.

Accordions
Enables authors to transform sub-headings into expand and collapsable blocks of content. The accordion component should be used within help articles to chunk content by sub-topics, infinitive phrases, step procedures exceeding 9 steps, or to replace “see topic xyz” links.

Accordion Tags
To use use the accordion component, you will apply specific tags in your html files whether you are working from MadCap Flare, Dreamweaver, or other development tools.

Redlines

Help List

ContainerDrawer Basic View
Dimensions20px margin above article title and below article excerpt
10px between title and excerpt
TypographyArticle title is a Large Label, with link formatting
Article excerpt is Small Body
Excerpt length is limited to 80 characters
ContentFinal item in list is always the standard 'Contact Support' article

Article Detail

ContainerDrawer Detail View for articles from the help list
Drawer Basic View for standalone articles
Title is 'Help Topic' for standalone articles
TypographyTitle is a Level 2 Heading
Other headings scale to leave the title as the largest heading
Main content is Small Body
Lists, italics, bold, and other basic typography features follow the standard Typography component styles

Embedded Activation

Iconquestion-circle
Large Label sizing
Link formatting
TextBasic Label
Link formatting
UsageShould be physically located near the relevant part of the page
Choose either the icon or text style per page, don't mix and match

Accordion

Spacing12px above, below and between accordions
6px separating the title from accordion content
8px padding between icon and title
TypographyTitles are Bold Labels, Primary Color
Accordion content follows the same type style as the surrounding text
Iconcaret-right for unopened items, caret-down for opened
BehaviorUsers can open accordion items independently from each other (i.e. opening an item doesn't autoclose other items that are already open)

Tips & Notes

SpacingTitle and content have 10px horizontal padding
4px vertical padding for the title
6px vertical padding for the content
Border1px hairline gray line separating title from content
Iconslight-bulb-o for Tip
info-circle for Note
exclamation-circle for Important
8px padding between icon and title
TypographyContent is Small Body Copy
Title is Bold Label, Primary Color
ColorsOff White (#f2f2f2) background for titles
Brightly Lit (#e6e6e6) background for content

Changelog

1.0.0

Initial version