Writing Online Help

Member Submitted

This document gives information and recommendations on writing online help text.

There are many ways to find information in a book:

  • Table of contents
  • Index
  • Chapter titles

These same ways exist for online help, but they are used in different ways. For online help, the primary ways are:

  • Context-sensitive (user pressed the help key)
  • Search function
  • Free form (user is following links to explore a topic)

The online help ways share something in common: they are all very similar to trial and error. Instead of turning to a particular page and being reasonably certain the information they are looking for is there, in the online help model they click on many things in rapid succession looking quickly at each one, reasonably certain that the information they are looking for is not in there, but is in there somewhere. Because of this difference in user behavior, it is very important that each information chunk has a clear section title that identifies the topic and the main points for that topic in an easily understood manner. The user may only spend a couple of seconds looking at each one before moving to the next possibility, so the better the titles, the more retrievable the information.

Books, even reference books, are structured in a linear fashion. Pick up any product book, and you’ll find the following:

Beginning Edition notice, preface, about this book
Middle Chapters containing the primary information, organized by category
End Appendix, glossary, index

Online help has none of this. Instead of having an imposed structure like a book, the structure of online help is instead defined by the product, and by the way the user interacts with the product. Because of this, you can never know what the user has already read. So, each help topic must be standalone. However, you can be fairly certain that the customer has the product up and running, and is at the right place. So, each help topic as linked to the part of the product it describes. This means that background information is largely unnecessary, and diving right into the topic is appropriate.

There is nothing that better highlights the differences between traditional book writing and online help than the concept of hypertext. Hypertext allows you to find those spots where the reader of a book might flip through the pages to look something up, and make it instantly available. It is a powerful, time and energy saving concept. It also fits well with the overall theme of online help, which is brief and direct. If background information is needed on a previous function, for example, stating that and making the function name a pointer to the section containing the needed information will cover the requirement without using much of the limited screen space.

It does warrant caution, however, as too much hypertext can cause the reader to become hopelessly lost following all the threads. Because of this, it is best to only use hypertext links when required, and restrain yourself from adding links just because they might be relevant. If the user gets lost too many times, they will stop using the help.

Economy of words
The usual practice in technical writing is to divide the book or document into subparts or categories. Chapters, sections, and appendices are the result of this categorization.

The same practice is done in online help development, but the sections are much smaller. This is because of the limited screen space available. Flipping through a book looking for things and reading along the way is expected, flipping through lots of online help is not. For this same reason, all unnecessary words, sentences, and descriptions are pruned

About the author

AgileConnection is a TechWell community.

Through conferences, training, consulting, and online resources, TechWell helps you develop and deliver great software every day.