FAQ > Online Documentation

FAQ: Online Documentation

What is "online" documentation?

Why would I use online documentation instead of printed manuals?

Are there still advantages to printed documents?

Are there cost considerations for having online documentation?

Is there a difference in formatting and document structure between online documentation and printed manuals?

Are there different kinds of online documentation?

Why use Windows Help to distribute online documentation?

What is "online" documentation?

Documentation of any kind that is electronically available to the user any time it's needed. The most common distribution methods have the documentation on network servers or on your intranet so that the developers can easily maintain it.

Why would I use online documentation instead of printed manuals?

The online documentation is available immediately.
No notebooks taking up shelf space (how much room do you have in your office?).
Always up to date with the latest version; no one has to wonder if they have the latest paper revision.
Very few distribution problems. Usually online documentation can be "updated" automatically by one person running a batch or script file during the night. The next time a user looks at it, it's automatically the most recent.
With paper, you have to create instructions, print a master, duplicate (lots of) copies, distribute it to (lots of) people, and hope they can find the notebook and actually put in your update. How much does that cost in paper and time?

Are there still advantages to printed documents?

Definitely. Online documents require an operating network/intranet. There are emergency situations where you may not have a operating system available, such as a power outage.

In a case such as this, you may well need printed documentation. We have one client who put his Emergency Recovery Procedure in both printed and online format. By maintaining the online format, it is always available for use and review. He could make a printed manual master from the online source in 15 minutes from the time he decided to print a manual to the time the last sheet rolled out of the printer. He then distributed both the printed manual and a diskette with the online procedures to the department heads. They could then use the diskette if they had a laptop, or just use the printed manual.

Prints are still quite useful for things like Quick Reference Guides and cheat sheets. The guideline for printing is based on:

How often is the information updated? The more frequently it's updated, the more reason to use it online.
How large is it? The larger it is, the less often it should be printed.
How often is it used? The more frequently it is used, the more reason to print it (and maybe post it on the wall).

Are there cost considerations for having online documentation?

Two major considerations:

Materials cost
Labor cost

With printed documentation, you have the cost of duplication, manual covers such as notebooks, and physical shipping. With online documentation, these costs go to zero.

The labor involved in paper distribution includes not only that of duplication and distribution as above, but also in the time the end user takes to update the manual he currently has. If you're doing a complete manual replacement just to change several pages, it still has the same cost as if you re-did the entire manual. This is one reason why many organizations have their manuals so out-of-date.

Is there a difference in formatting and document structure between online documentation and printed manuals?

Usually there is a considerable difference in both formatting and structure between the two documentation types. The output medium is considerably different, and the typical use is usually different. Here's a comparison:

Online	Printed
Low resolution; 72 to 100 dpi	High resolution; 300 dpi and above.
Smaller visible area, typically equivalent to 7" wide by 4" high.	Any size you can afford, usually letter-size of 8-1/2" by 11".
Rapid searches	Slow searches; if you have a good Table of Contents and an excellent Index, you're usually in good shape.
Can have built-in multimedia (animation, audio, video).	Static.
Color.	Usually black and white or grayscale. Color gets quite expensive very quickly.
Hypertext -- rapid moves to any part of the documentation.	User has to find the reference manually and flip the pages.
Only one part (a screen full) visible at one time.	Can have a full page visible, plus can mark several other pages (sticky notes as tabs).
The window is resizable down to a very small size; this means the formatting should be designed with the left side of the screen in mind.	Fixed size. Can use the full variety of formatting and indents to convey structure.

Are there different kinds of online documentation?

Many different types. Many consider that putting some Word documents out in a shared file server directory to be "online documentation". However, this gives no method of searching more than one document or going between documents. Opening a document in Word takes both time and computer resources, so this is not a very viable solution.

A design decision needs to be made at the beginning of the documentation project -- is the documentation's major purpose to be viewed (and searched) online or to be printed. If the major purpose is for print (formatting, fonts and document structure have high importance), then Adobe Acrobat Portable Document Format (PDF) is a good choice. With the proper design and setup, you can create a system that enables the user to search for and print documents.

If the major purpose is for online search and viewing, not print, then you need a different format. If you have an established intranet operating, then you can use either WebHelp (which creates a stand-alone, packaged manual) or Web pages like a website. If you have a standard network, then you can use Windows Help, which comes in various flavors.

Windows Help formats differ, but they generally have these features in common:

Graphical navigation and organization support (indexes and Tables of Contents)
Popup or glossary topics
Browsing sequences (automatic next and previous page)
Full-text searching for specific words or phrases

WinHelp

Used primarily as application and standalone Help (like online manuals) for systems using Windows 9x/NT. The original versions (3 and 4) have the advantage of using incremental data transfer; you can have a 10 Mb Help file on a server, but only a few kilobytes at a time are transferred on demand across the network. CKI recommends this format because of its simplicity, low network load, and special full-text search capabilities.

Microsoft HTML Help

This is the style Microsoft introduced with the later versions of Windows. It usually displays as two major panes; the Table of Contents/Index etc. on the left and the material on the right.

The HTML Help files are meant to be used on the local computer system, not across a network. The entire file is loaded when you run it, so it would place a heavy load on a network.

WebHelp

This is for use on an intranet and enables you to package your documentation and give it a totally different look and feel if you desire. It's main advantage is that it can be placed on one Web server and all users can access it from their with a Web browser.

Why use Windows Help to distribute online documentation?

Three major reasons:

Your users already have all the software they need already installed. All versions of Windows have the Help program in place and operational. There is usually no need for any additional installation, usually only an icon (shortcut) to the main menu.
Windows Help using RoboHelp has the best contextual search available.
No extra licences or fees. The authoring tool is a one-time cost, with unlimited distribution rights.