Help Systems

One of a series of white papers by Elizabeth G. Fagan dba EGF Consulting. Fagan learned these standards and conventions working as a Microsoft Help Author at Microsoft in Redmond, WA.


Focus on the User’s Point of View

Users seek help when they are frustrated. They have tried to accomplish the task they set out to do and have been unsuccessful. Very likely, they clicked the help icon as a last resort and are now in a hurry to complete the task. Imagine yourself in that place.

Address the Needs of Specific Users

Create personas—specific profiles that represent the spectrum of users. Then make sure the system addresses the interests of those personas. Avoid writing help topics for “average” users who may not actually exist.

Think “Top-Down” for the Table of Contents

Users begin scanning the top of the table of contents (TOC) and work their way down. Put need-to-know topics at the top and do not hide them under collapsed lists. Place advanced or optional topics at the end.

Provide an Index and Search Tool

Novice users tend to seek help through the TOC; intermediate and expert users tend toward the index and search tool. Make sure your help system accommodates them.

List Common Tasks as Actions

Users skim the help system’s TOC for the task they want to complete. Write TOC entries as verb phrases that clearly and sequentially address the tasks most frequently performed. List subtasks under main task headings.

Be Concise and Consistent

To avoid redundancy and potentially conflicting information, write about a subject only once and link to it when relevant. Focus on one task or topic per page and eliminate unnecessary detail or general discussion. Use consistent page elements.

Define Terms and Acronyms; Eliminate Jargon

Developers and stakeholders know application-specific terms and acronyms. Users seeking help may not. Write TOC titles and topics that users new to the application can easily understand. Use everyday language and define acronyms at the first instance on each page.

Write Meaningful Links and Use Liberally

Linked text should clearly anticipate the title of the linked page. To aid scanning, consistently isolate links from running text; use bulleted lists, for example.

Use Examples and Numbered Lists

When appropriate, supplement complex tasks or concepts with examples. Capture steps as action phrases and write them as numbered lists. If a single step is involved, use a bullet instead.

Write Clear and Distinct Topic Types

Develop a standard template for different topic types. For example, concept topics and procedure topics should look and feel distinctly different, as follows.

Example Concept Topic
Lorem ipsum dolor sit
Volutpat sollicitudin suspendisse diam commodo pede dolor non faucibus donec placerat nullam porta leo mauris.

  • Ut pulvinar dictum.
  • Sollicitudin tortor id.
  • Mauris faucibus praesent.

Sagittis quisque eu
Sed volutpat gravida dui lectus ultrices risus fusce morbi sed phasellus exercitationem at enim nullam habitant non vel pede justo praesent quis donec aut sed urna hendrerit.

Example Procedure Topic
Lorem ipsum dolor sit
Volutpat sollicitudin suspendisse diam commodo pede dolor non faucibus donec placerat nullam porta leo maurisSed sed vitae posuere mauris nec

  1. Ut pulvinar dictum.
  2. Sollicitudin tortor id.
  3. Mauris faucibus praesent.

Sagittis quisque eu
Sed volutpat gravida dui lectus ultrices risus fusce morbi sed phasellus exercitationem at enim nullam habitant non vel pede justo praesent quis donec aut sed urna hendrerit.