How to Plan On-line and Paper Versions of a Software Manual

Home / Archives / Back Issues 1991 /

Many software companies offer both on-line and paper documentation with their products. For example, Microsoft includes an on-line help file and a paper reference manual with Microsoft Word, their high-end word processors.

On projects for which you must produce both on-line and paper documentation, there are many things you should consider before you start. For instance you might ask the following:

• How do you plan the on-line and paper versions of a document so that you are not unnecessarily duplicating work or wasting time?
• How do you cross-reference information in and between the manuals?
• How does the format of the documentation (paper or on-line) affect its production?

You cannot just take the paper version of a manual and stick it on-line; the two media have different purposes and thus different requirements. By carefully considering the questions above, you can save yourself effort, time, and aggravation. At the same time, you can make the on-line and paper documents easier for people to use. In this article, I present some of my ideas on the following subjects:

• Planning on-line and paper versions
• Cross referencing information
• Formatting the two versions.

Planning on-line and paper versions of the same manual

Usually, you only have a limited amount of time in which to produce the on-line and paper versions of the manual. You can save time and effort considering the following suggestions before planning the on-line and paper versions of a manual:

• Plan the paper manual first, then the on-line manual. The on-line version of the manual should be a subset of the paper manual. All the information in the on-line manual should appear in the paper manual.
• Chunk information into the smallest practical units. Good on-line documentation should have all the information about a subject visible on the screen at the same time. This means you have to eliminate scrolling as much as possible and that you should use a modular approach to the manual.
• Plan to write the on-line manual first, then the paper manual. Because of the format, on-line documentation requires information to be in small, discrete chunks. If you followed the previous suggestion, when you write a section for the paper manual, all you should have to do is take the information from the corresponding section of the on-line manual and expand the entry as you like. You will need to add introductions for the manual itself, chapters, and sections.

By following these suggestions you can save time by writing the main portions of the manual only once.

Cross referencing information

In a paper manual, you direct users to more information on a topic through the index. In on-line documentation, you need to give the user a way to get more information either from other sections within the on-line manual or from the paper manual.

When directing users to more information, keep these guidelines in mind:

• Give users a way of navigating directly from one topic to another topic. This way the user does not have to go searching for the necessary information.
• Give users a way of getting back to the topic they just left. This reduces the amount of manual navigating a user has to do.
• Give users a one-step way of getting to the main level of the on-line help file. This can prevent users from getting lost while searching for information, and help them regain their bearings if they do get lost.
• Give page numbers, section headings, or chapter headings from the paper manual in on-line entries. This has to be done after the paper manual has been written and fixed, so it happens late in the development cycle of the on-line manual. Giving these directions to the paper documentation gives the user another source of information and helps make the two manuals seem like part of the same documentation set.

Formatting the manuals

The paper and on-line manuals will have vastly different formats. On-line documentation has different requirements than paper documentation, thus, needs to beformatted differently. I have listed three of the most pesky concerns you need to consider when formatting on-line and paper manuals:

• Colors. Use no more than four colors in a document, and no more than three on a page at one time. You must exercise great care when using color in on-line documentation. For instance, will all users have or be using color monitors? What do you do if they do not? The colors you choose should match those of the paper documentation. Doing so builds user confidence and helps bind the two documents into the same documentation set. The colors you choose should stand out easily. Black, red, and blue work well; yellow, green, and white do not. You also must remember that approximately ten percent of the population is color blind. Obviously, graphics or other examples are not included in this suggestion.
• Fonts. Use sans serif fonts for on-line documentation. Studies have shown that sans serif fonts are easier to read on a screen than serif fonts. However, on paper, serif fonts are easier to read than sans serif fonts. You also must take care in choosing the fonts you use. Will the users have these fonts in their computer or will you have to have the user install the needed fonts? What do you do if the user does not have the needed fonts? You have to think about these questions before you format the manual.
• Spacing and alignment within a manual. With paper documentation, you use tabs and margins to align text. In many on-line documentation systems, you cannot use tabs or have different margins for different sections of text. This is not as trivial a problem as it seems, for, what do you do about indentation? If you use a proportional spaced font, the width of each character is different. The margin of even the most painstakingly aligned document that uses proportional spaces will look like the line two drunks left as they walked down the street arm in arm. It certainly won't look good.

Conclusion

In this article I have given you guidelines on planning, cross referencing, and formatting on-line and paper versions of manuals. There are many other things to consider, too many to mention here. For instance, what kind of information (i.e., instructions, reference, background material) is best suited for on-line documentation? What kind is best suited for paper documentation? How do you best organize information in an on-line document? What are the pitfalls of on-line documentation? Although this document does not answer these questions, the sources listed below can help you find the information to do so.

Sources:

Apple Computer, Inc. 1987. Human Interface Guidelines: The Apple Desktop Interface. Reading, MA: Addison-Wesley Publishing Co.

Burke, Kathleen and William W Wright, Jr. "Making on-line documentation helpful: Applying what we've learned" American Institutes for Research, 1986.

Garner, Kathleen H. "Checklists for On-line Writing" Handout from ENG3616, Spring 1990.

Gomoll, Kathleen and Anne Nicol. "Human Interface Notes. Note #2: Discussion of a set of criteria and guidelines for on-line help." Apple Computer, Inc. January 1990.

Kremin, Michael C, (Information Engineering Associates) and Donna R. Dolan (BRS) "The development of a checklist for the evaluation of computer documentation. A case study of current on-line vendor documentation" American Institutes for Research.

Powers, John R., III "A Template for an On-Line Help System in C," MacTech Journal Autumn 1990, p. 55.

Price, Jonathan. How to Write a Computer Manual. Reading, MA: Benjamin/Cummings Publishing Company, 1984.

Weiss, Edmond H. How to Write a Usable User Manual. Philadelphia, PA: iSi Press, 1985.