by Jean Hollis Weber
This paper describes some common types of help topic and when to use each.
See also my paper titled Planning an online help project.
Different applications require different mixes of help topics. Choose the topic types that are appropriate for the application you are documenting.
Notes:
- The names given to the topic types in this paper are for convenience only; they do not appear in the online help itself, and other sources of information may call them by different names.
- You can use other help topic types (for example, tips and tricks, troubleshooting, tutorials, “show me” help, and reference help such as syntax diagrams for programming languages), but they are not covered in this paper.
Typical topic types
- Overview
- Brief description of the application’s purpose, intended use, and most common or important tasks.
- General (window-level) help
- Describes the active application window, what it does and how it works.
- Procedural (how to) help
- Step-by-step instructions on how to complete a task.
- Conceptual help
- Information about the theory, logic or reasoning behind a task, or about fundamental concepts, components or actions in an application.
- Field level help
- Also called “What’s this?” help in Windows 95. Help for individual fields and controls within a window.
- Frequently asked questions
- Answers common questions that users may have when working with the application.
- Message help
- Information about error messages and how to respond to them.
Overview topics
Overview topics provide a brief description of the application’s purpose and intended use. They may be presented as a single topic (if brief) or a sequence of related topics.
Overview topics typically contain:
- Purpose of the application
- Description of changes and new features that will affect users and their work
- Guidance on where users can get help or application support
- How the user can get started with the application (for example, a brief description of the navigation options)
- How the user can get help on the application
- Brief description of the most common or important tasks a user can perform, with links to the procedure topics
- Brief description of user roles, if any
General (window-level) help topics
General help provides information on how to use the active window or dialog box, a description of tasks that can be accomplished with the window, and details on window elements and processing.
This is the topic that should be displayed when the user presses F1 or a Help button on an application window. In some cases general help can be combined with procedural help, for example when a single sentence or brief paragraph is sufficient to describe the window.
General help topics typically contain:
- Window title
- Brief overview of the window’s purpose or use, from the user’s perspective
- (optional) Processing rules
- Procedures for the tasks a user can perform with the window or links to such procedures
- Description of fields, push buttons and other controls or links to such descriptions (may be contained in popups on a graphic of the window)
Procedural (“how to”) help topics
Procedural topics are designed to achieve the following goals:
- Describe work tasks that users want to perform
- Guide users through work tasks by supplying step-by-step instructions
- Provide a task focus by using terms familiar to users and relating new concepts to work tasks users will try to complete
Procedural topics provide step-by-step instructions on how to complete a task. This often involves more than one window or dialog box. Graphical roadmaps might also be provided. Task procedures explain how users complete their tasks and achieve a desired outcome.
Procedural help topics typically contain:
- Task title (briefly identifies and describes the task procedure)
- Purpose of task or procedure from the user’s perspective (a sentence or two that explains the task purpose, its usefulness, and the expected outcome or result)
- Prerequisite conditions or tasks that users must perform before beginning this task
- Step-by-step instructions or procedure (numbered steps that describe how to complete the task)
- What happens now? What happens after a user performs the task steps (outcome; results and follow up information)
- Related topics list
Conceptual topics
Conceptual topics provide information about the work, specific tasks or workflow process, including its purpose, the way information flows through the process, specific outputs produced or tracked within the process, and the people involved in the process. Conceptual topics try to answer questions like “What is the process?”, “Why is it performed?”, “Who is involved?”, “What is produced?”, and “When is information needed?”
Conceptual topics are designed to achieve one or more of the following goals:
- Present concepts to users
- Provide an overview of the workflow process and task steps
- Provide a general description of the people involved in the process and their roles
- Discuss business processes or rules
- Describe end products that users create when using the application
- Describe objects or resources that users work with during the business process
- Discuss how to get started using the application
- Share useful working tips
Since concept or process information will vary significantly across applications, there are no typical sections for conceptual topics.
However, you should create a style for these topics and apply it consistently across all conceptual topics within the application. For example, sample sections for each topic might include an overview or introduction (“What is a <concept or object name>?”), a section on the process or object purpose (“Why is a <concept or object name> Created?”), a section on how objects fit into the process (“How Does <object or person> Fit into the Process?”), and a section on related topics. Include a Related topics list.
Field level help topics
The usual purpose of field level help is to answer the question “What is this and why would I want to use it?” For entry fields, it should also answer the question “What do I type here and what restrictions are there on how I enter the information?” For example, dates typically need to be entered in a particular way; some fields may be case-sensitive while other fields may not.
Field level help usually includes a brief description of the information that should be typed into the field. It might also include information about why a setting might be disabled and how the user can enable it.
In Windows 95, this help is called “what’s this?” help and appears in a pop-up window sized to the text.
Since the information needed at this level will vary significantly across applications, there are no typical sections for field-level topics. However, you should create a style for these topics and apply it consistently across all field-level topics within the application.
- Because these are pop-up topics, they do not need a heading, but you might prefer to include one.
- Keep these topics brief, and include only essential information.
- Do not include a Related topics list.
- In Windows 95, do not write help for common buttons like OK, Cancel and Help. Windows 95 automatically provides Help for these.
Frequently asked question topics
Frequently asked question topics answer common questions that users may have when working with your application. These questions typically involve tool-related quirks, such as areas where the tool behaves differently from other applications or from what users expect. Example questions are:
- Why can’t I find the name of a strategist in the list?
- Why can’t I edit a document?
- Why can’t I view a document?
- Where is the “relationship plan”?
You can build a list of common questions from user-centered activities, such as walkthroughs, usability evaluations, pilots, discussion databases, and so on. This does not mean that all user questions must be answered in a frequently asked question topic. Some questions may be answered by enhancing procedure or concept topics.
Frequently asked question topics typically contain:
- Title containing the question (for example, “Why can’t I print?”)
- An answer to the question. You may need to include procedural steps or include a link to an existing procedure.
- Related topics list.
Message help topics
Message help topics provide information on common error messages and recommended solutions: additional guidance (beyond what is in the message itself) on how to solve a specific problem. They should be used infrequently. The goal is to design clear and effective messages so that these topics become unnecessary.
Message help topics should contain:
- Actual message title
- Brief explanation of the problem
- Possible solution or pointer to a help source
Last updated 3 March 1999