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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Develop a standard template for different topic types. For example, concept topics and procedure topics should look and feel distinctly different, as follows.