Organizing your online Help
When you write your online Help, try to think in terms of types of information: overview, procedure, and reference information. If you cover one type of information in a topic, this helps keep your topics short, skimmable, and easier to understand in an online delivery system.
- Overview - Contains narrative information and graphics about one functional area or a group of commands. Procedural information and references to the user interface are described sparingly in this type of topic and only when absolutely necessary. The following example from Microsoft Help illustrates an overview topic:
- Procedure - Contains information about how to do a certain operation in the software. These topics are usually no more than eight steps, although exceptions do exist.
- Reference information: Command topics - Defines each command in the software with a detailed description and links to related dialog boxes, ribbons, etc. You should also discuss how to use the command, when it is available, and what sorts of options are available when using the command.
- Reference information: Ribbon, toolbar, dialog box, and tab topics - Lists gadgets with a detailed description of what each gadget does. You should cover how to use the gadget, when to use with the gadget, why the user would want to use it, and how using it might affect other options. This type of topic is sometimes referred to as a reference topic. You can also cover this type of topic with What's This? Help topics, also called right-click Help or shortcut Help.
- Common task topic- Contains lists of commonly-used procedures for a specific functional area.
Tips
- Before you write your online Help, take screen shots of each window and dialog box. Place them in a Word document and print them for later reference. This will save you a lot of time when you write your topics. Using the printout is faster than trying to switch back and forth between the software and your Help authoring tool.
- When writing a topic for a dialog box, tab, or ribbon, list gadgets in the order in which they appear left to right, then top to bottom. If you are writing about a dialog box with tabs, make a list of tab titles in the order in which they appear from left to right.
- To find out the name of a gadget on a ribbon, point to the gadget and read the ToolTip. Use the exact ToolTip text for the gadget as the gadget name. If the ribbon does display a name for the gadget on the ribbon, use that name instead of the ToolTip because customers would see that first.
