Use the following to get you started learning what online helps are, how they are structured, what sorts of information goes into them, and so on.
You know what online helps are. You may have used them in the past. They are those smallish windows that you display over the work you are doing in whatever application you are using. You call up helps when you can't remember how to insert a page number in a document, for example. That's how online helps are often defined: quick-reference information, quick memory joggers. Even so, some developers put full-blown tutorials in the delivery medium of online helps. But typically, online helps are a small subset of, for example, the typical printed user guide for an application. It's just not practical to duplicate all that printed information in the online medium.
For most software applications—or that matter, any application that has a computer-monitor interface—you'll find help menu items, help buttons, and help icons. Two are displayed in the following:
Menu items and icons for online helps.
The key components of online helps include topics, menus (like tables of contents) and submenus, hypertext links, popup helps, related-information links, indexes, glossaries, and search capabilities.
Topics. In the online-help world, chunks of information are called topics. As you navigate around in helps, each full screen of information is a topic. In other words, everything included from the top of the information to the bottom of it, at that point you can't scroll any farther. You arrange the topics of an online help system as you would any other hypertext. You create hierarchies or sequences and link them all up together. In the following illustration, each rectangle is a topic (a "chunk" in hypertext talk). This hypertext is structured hierarchically—n other words, your movement through the hypertext is controlled by menu choices and submenu choices.
Topics and their relationships in an online help system.
Menus and submenus. When you click on a help button, one of the first things you typically see is a menu of choices indicated by link underlining. The following screen capture shows you two styles of TOCs. On the left is an early style: click on any of the links, and the entire screen changes to the information you requested. On the left is a more recent style: the TOC panel stays visible on the left side at all times. When you click on a link in the TOC panel, the information you requested appears in the right panel (often called the "reading" panel or frame)
Different menu styles for online helps.
Pop-up helps and inline pop-ups. One final important characteristic of help systems is popup links. Typically, you'll see dashed green lines under these popup helps. They produce something similar to what you see in the illustration below. When the reader clicks somewhere else on the screen, the popup goes away. This is an important feature in that the reader can get a quick bit of vital information immediately without leaving the topic and possibly getting lost. In this example, the reader might have a question about what the term RGB means and, seeing the word underlined, clicks on it to get the popup definition that is showing in overlaid portion of this screen capture.
Pop-up helps: click RGB and the pop-up help "pops up" with a definition of the word.
More recently, inline helps have been implemented. As you can see in the next screen capture, the pop-up help actually expands "inline" at the point where it is needed. In the screen capture, you'd first see the word index underlined. When you clicked on it, the blue italicized text would "pop in" to the line.
Inline pop-up helps
Related-information links. The screen capture just above illustrates another essential ingredient of online help topics. At the bottom of the reading pane, notice the help writer has identified a couple of closely related procedures that readers will probably want to view as well. As a help writer—and as an online documentation writer in general—you must anticipate readers' needs much more carefully and accommodate those needs, as in this example. Of course, the links to related topic need not be limited to the bottom of the help screen; they can be placed inline within paragraphs as necessary. Look at the previous screen capture illustrating inline pop-up helps. The button at the bottom provides links to closely related information.
Glossaries, indexes, and search. In the preceding screen captures, you can see menu options and tabs that provide users with glossary terms, indexes, and search capability. As an online help writer, you write the glossary terms and develop the index, but the help engine itself handles the search functions.
To write good glossary entries, you need to know how to write extended definitions. You also need to include synonyms for your glossary terms: words that some users may use instead of the ones you prefer (for example, floppy disk as opposed to diskette). Include those non-preferred terms in the glossary, and set a "See" link to your preferred term.
To write good indexes, you need to know something about the art of indexing, a brief introduction to which is provided in this program. As with glossaries, include terms some users might use but you don't use; include those nonpreferred terms in your index, and set "See" links from them to your preferred terms. Also, learn how to use your help-authoring software to make the index link point directly to the spot in the topic where the information occurs. This is not easy in most help-authoring software because the default is to link to the top of the topic. Typically, you have to create a "bookmark" at the specific point within the topic and link to it.
Glossaries, indexes, and search in online helps.
Programs and information provided by firstname.lastname@example.org.