Writing Online Help

[article]
Member Submitted

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.

AgileConnection is one of the growing communities of the TechWell network.

Featuring fresh, insightful stories, TechWell.com is the place to go for what is happening in software development and delivery.  Join the conversation now!

Upcoming Events

May 04
May 04
May 04
Jun 01