Contextual Help
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.
