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.

Structure
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.

Hypertext
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 prior to the final production.

In a book, a section might be a collection of eight to ten paragraphs. In online help, a section often consists of a single paragraph.

Before example
The square objects displayed on the screen number in the hundreds, and are a variety of different status colors. There are seven distinct colors to indicate status. Red status indicates a problem, while green indicates a fully-functioning object.

After example
There are hundreds of square objects, each of which is color-coded with one of seven status colors. Red indicates a problem, while green indicates a functioning object.

The difference between the two examples may seem slight, but a topic that consists of ten such paragraphs is ten lines longer with the "before" paragraphs, and ten lines shorter with the “after” paragraphs. This is a significant amount of on-screen space, and may mean the difference between having to scroll to read the entire section, or being able to easily read it all at once.

Reusable chunks
In a book, chapter orders are often changed or moved to different books. On online help, information chunks are often linked to from multiple places. The information order isn’t linear, like a book is, and more closely resembles a spider web, with all of the chunks and links between them. This matters because you cannot assume that the reader has read particular things prior to reading the current chunk. Each chunk of information must therefore be small and selfcontained.

When done correctly and carefully, this has great advantages. Individual chunks can be moved around and shared at will, without the careful planning required for a book. So, while there is an increased amount of time writing them, the end result is far more flexible than a book.

Before example
One type of object is the square object, which represents a router, or cluster of routers, and is color-coded to indicate status. To manually change the status, right-click on the object and select the desired status from the pop-up menu. After changing the status, proceed to the next section to learn how to define other kinds of objects.

After example
The square object represents a router, or cluster of routers, and is colorcoded to indicate status. To manually change the status, right-click on the object and select the desired status from the pop-up menu.

The "before" example contains transition statements, that guide the user from the previous section and into the next one. These statements also limit the ability to use this chunk in multiple places, as it assumes a context and surrounding topics. By removing the transitions in the "after" example, the text becomes portable, and can be used in multiple places without change.

Page size
Pages need to be short, to minimize scrolling. Using hypertext links to make the main text shorter will shorten the page, but increase the chance that the reader will get lost trying to follow the thread. It is best to minimize page size by keeping the writing short and concise.

Editing
Traditional book editing is done with a pen and paper. While it is possible to do this with online help by printing it out, this isn't the format the reader will be using. Links won’t work, color-coding and font styles may be lost, and everything is completely out of context.

A good way to edit online help is to first print out all of the help topics, then navigate to different points in the product and display them. The printed version will allow easy notes and corrections, and will ensure that all of the topics are reviewed. Viewing them online will ensure that links can be tested, fonts will be correct, and the context will be clear.

Define your audience
If you can't figure out who your target audience is, you'll be forced to write for all of them. Even if you could do this in a clear manner, the size of the topics would be prohibitive. If you can, define a single typical user and write to that only. If necessary, pick two users: a basic user and advanced user, and put the advanced section at the end of the topic.

Say it quickly
The user should be able to tell what your topic is within the first two sentences. This is because online help is often quickly scanned through, and if your point is buried in the text, the entire topic could easily be skipped. State your conclusion first, then go from there.

Before example
This screen covers over two-hundred individual objects, so you may need to scroll to display them all. Each object contains ten or more attributes, which can be changed by the Preferences choice on the menu. Use this choice to color-code the objects into groups.

After example
Color-code the objects into groups by using the Preferences choice on the menu. Each object contains ten or more attributes, which can be changed. The screen covers over two-hundred individual objects, so you may need to scroll to display them all.

Test your links
Nothing says unprofessional like a link that doesn't work. Not only does it call into question the validity of the work as a whole, the reader also doesn’t get the benefit that the link was intended to provide.

Because a properly written help system typically has hundreds, or even thousands, of links, it is impossible to adequately check them all by hand. Spot checking is okay, but leave the full-scale validation to a program. Most commercial HTML editing programs contain link checkers as well, so if your help is written in this format, you can use the editor itself to validate it.

View your document under different conditions
The old pop up dialog box that recommends a particular resolution and color depth for ideal viewing is extinct. You can assume that your readers are running your help on a variety of different computers, operating systems, and web browsers, and they aren't going to change their computer just to read your help. While you don't have to make certain it works under all of them, it is important to try it out to see what the limitations and display differences are, and to attempt to compensate for this as much as possible.

For example, it is useful to place graphics inline in the online help text. If you create these graphics with a full color palette, they will look strange to users running under a smaller palette. By decreasing the number of colors in the graphics, this limitation is removed, the graphic files themselves are smaller, and everyone is happy.