Developing panel help

A panel-help plug-in contains a set of topics, which are independent units of information that are meaningful when displayed alone. This topic-based structure allows you to create context-sensitive help for each page and window displayed in your application. Topic-based content can contain task, concept, or reference information.

These information types are described in the following sections:
To provide context-sensitive help for your application, use the XHTML tagging language to create the following topics:
  • An introductory topic that provides a brief description of the task and highlights its key features.
  • A separate topic for each page or window in the user interface that explains the purpose of the panel and describes the elements on the panel including any fields, columns, actions, or buttons.
  • A separate topic for each action that provides step-by-step instructions for performing the action.
  • A separate topic for any concept or reference information required for users to effectively operate your application.

Task topics

A task topic uses a series of steps to explain how to accomplish a goal. Task topics provide procedures, typically in step-by-step instructions. Some task topics might list choices, as bulleted points rather than steps, or they might describe a single action rather than a sequence of steps. Tasks topics also provide information about the context (where to perform a task and when), the rationale (why perform the task), prerequisites, and examples.

Supertasks (high-level tasks) are the starting points for most users. Steps in a supertask often link to sub-tasks. Each sub-task is documented as a separate task topic. These tasks can be part of one supertask or many. For example, in database programming, opening a database connection is a task that can be reused in several high-level programming tasks.

A task topic documents what users need to know to successfully complete their work. As you write task information, note what concepts need to be documented, and to what depth, if users are to complete the tasks successfully. Consider the probable skills and experience of users, and write with those characteristics in mind. For example, if users need to configure TCP/IP (a task) and might not know about routers, create and link to a concept topic on routers.

Remember these main points when you write task topics:
  • Document the steps that users follow to accomplish their goals.
  • Use a verb phrase (gerund) as the heading for a task topic.
  • Use an opening paragraph to provide context for and introduce the task.
  • If the task has a prerequisite, provide that information or provide a link to that prerequisite before the list of steps.
  • Use a numbered list for the steps that users must follow to complete the task.
  • Write the steps as brief imperative sentences.
  • When the user's context changes, introduce the step with a phrase that establishes that new context (for example, On the Configuration page, ...).
  • Write one step for each significant user action.
  • If a task has more than nine steps, try to divide it into two or more separate tasks.
  • If the task is part of a sequence of tasks, provide a link to the next task.

Concept topics

A concept topic describes a system, solution, product, tool, feature, or background information that users need to complete a task. Users typically read concept material before tackling some large project or starting to use a product or tool. In contrast, users need task or reference topics when they perform a task.

A concept topic describes the scope of the topic and clearly defines what the topic is about. Use minimalist writing techniques to create content that users can quickly understand. Beware of turning a concept topic into a white paper by explaining the whole design philosophy of a product or component. Every concept topic performs at least one of the following functions:
  • Introduces a solution, process, product, tool, or feature.
  • Provides background information and explains issues that users must know before working with a system or component, or before starting a task.
  • Describes the benefits of using one approach rather than another, or provides information about when one particular choice or tool is more appropriate than another.
  • Describes how one feature, tool, or product is related to others, and how they work together or do not work together.
  • Describes any restrictions that limit the circumstances in which a tool can be used successfully.
  • Expands the significance of an important term beyond the scope of a glossary definition.
  • Explains how and why some behavior changes as time passes or work progresses.
  • Helps users form a mental picture that builds on the experience and knowledge that they are already likely to have.
Remember these main points when you write concept topics:
  • Document the background knowledge that users need to successfully use the system, process, product, tool, or feature.
  • Use a noun or noun phrase as the heading.
  • Use paragraphs.
  • If the topic is longer than two screens of information, use subheadings to break it into sections.
  • When introducing a new term, begin with a definition; then, expand that definition.
  • Add graphics when they simplify the explanation, for example, to show a process or the relationship among concepts.
  • Provide examples to bridge from unknown knowledge to known.
  • Address only one complete idea.
  • Keep the concept topic short and concise, but describe the concept completely.

Reference topics

Reference topics provide quick access to information that users are likely to need as they complete tasks. Use reference topics to document the purpose of an element, and any restrictions (such as case sensitivity), required authorizations, or anything else that might limit the use of an element.

There are several types of elements for which you can provide reference information. A few examples follow:
  • APIs
  • Commands
  • Language and programming elements
  • Class descriptions
  • Keyboard shortcuts
  • Protocols
  • Schemas
  • Settings
  • Symbols
  • Templates
  • Column, field, and action descriptions
Remember these main points when you write reference topics:
  • Use tables and lists to make reference information easy to scan.
  • Use a noun or noun phrase as the title for a reference topic.
  • For a particular category of information, such as API documentation, use a consistent format so users can find information quickly.
  • Be brief, but write in full sentences.
  • Do not go into long explanations; assume that readers understand the basic technology.
  • Make the topic as long as it takes to explain the subject.
  • Provide links to closely related reference topics, and in some cases, to related concept and task topics.
Parent topic: Creating help plug-ins