Classic Computer Magazine Archive ST-Log ISSUE 21 / JULY 1988 / PAGE 49

TUTORIAL

Read Any Good Docs, Lately?

by David L. Coles

Only seconds remain until the completion of your sophisticated program. The debugging finished, you smile in the knowledge that shortly the mail will bring the announcement of your induction into the "Coders Hall of Fame." But as you stagger off to relax it hits you—you're not through yet!

You've forgotten the little matter of documentation. No sweat, you reason; tomorrow you'll knock something out to guide the troops through the woods. Unfortunately, if you believe that will be sufficient, you're either too tired to think straight, or are grossly mistaken about the needs of computer users. Your software may well ensure your place in the Coders Hall of Fame, but do you really want all those angry users burning the documentation in protest during the induction ceremonies?

Inadequate or confusing documentation dooms many otherwise excellent programs to collect dust after only a few uses, while it prevents others from being used to their fullest potential. Rather than just "knocking something out," you have the responsibility to complement your software with good quality documentation. But don't confuse this with generating reams of paper. The task is to strike a balance between frustrating users with too little information and frightening them with too much. Ideally, you provide just the right amount of instruction to get the program installed, fully explain its operation, and provide ready references when a quick refresher is needed.

One very effective method of producing such quality documentation is for you to actually work through the installation and operation of the program yourself, noting each step as you go. These notes are then collated into an outline, and eventually become the backbone of your documentation. This article explains how to utilize this method, and presents some helpful tips to make your documentation more interesting. But the thought processes used for developing documentation are different than those used for programming. So, before you grab your favorite crayon to begin writing, set the project aside for several days, allowing sufficient time to clear your mind.

The logical way to start is to place yourself in exactly the same position that your users will be in when they first lay hands on your program. Only by treating yourself as a first-time user will you be able to spot some of the more obvious items ("Oh, did my documentation neglect to mention that you had to have BASIC on the working disk... sorry 'bout that!"). To do this you will need to start with a working distribution copy of your software, one that will be identical to the one users will eventually have. This means it should contain only the programs you will be distributing, without any operating system, interpreters, compilers, or other proprietary commands.

Program installation is usually a onetime function, so it is best to treat it as a separate section in the documentation. Installation might be simply a matter of getting the command(s) onto a "working" system disk; or it could involve implementing specific peripherals, or special command and/or data file configurations. In any event, work through all the various installation functions, keeping a step-by-step log of exactly what you did (and in what order you did it) until you have completed installing your program.

The operating instructions are the real heart of any documentation. As the program author, you have invested countless hours producing the program and are therefore familiar with every nuance of its operation. This section of the documentation has the task of successfully transferring all this operational expertise to the user.

Your program may be completely menu-driven, with the ability to walk users through its operation; or it may require that the user be familiar with special "commands." Either way, work through all the various operating functions, keeping a step-by-step log similar to the one you kept for the installation function. Once this phase is completed you will haved compiled a set of notes which detail every step necessary for installing and operating your program.

Next, you'll need to formulate an outline for your documentation. A representative, full-blown outline might include the following:

  • Cover Sheets
    • —Title page
    • —Copyright, disclaimers & warranty
  • Table of Contents
  • Introduction
    • —Program features, results, etc.
    • —Special notes (system configuration, etc.)
  • Getting Started
    • —System familiarization
    • —System start-up
    • —Creating backup & working disks
  • Installation
    • —(Part of your notes will be used here.)
  • Operating Instructions
    • —(The majority of your notes will be utilized here.)
  • Reference section
  • Index

With your notes and suitable outline, you're ready to begin writing the documentation. It may appear that the hardest part is yet to come. But remember, the majority of your documentation will come from the notes you have taken. What remains now is simply to transform these notes into an instructional text format and place them in the appropriate section.

To accomplish this, each function of installation and operation should be introduced with a function definition and an explanation of any associated options. The definition is followed by a narrative explaining how to execute the function and an execution example.

To illustrate, let's see how this might work for a fictitious program entitled "DOIT." Assume that the program is not menu-driven, but instead requires that all optional arguments be included in the "command tail."

DOIT is a program which. . .(definition would be presented here).

DOIT allows you to select various options. You may choose:

  • The drive containing the file you want DOIT to use.
  • The name of the file to DOIT to
  • The echo results to your printer
  • The number of times to DOIT
  • The individual record to start with
  • The field number to start with
  • The field number to stop with

These options are selected at the time DOIT is executed from the command (or ready) state.

To illustrate the operation of DOIT, let's assume:

  • Drive A contains the file you want DOIT to use
  • You want to DOIT to a file named FILENAME.EXT.
  • You want the results echoed to the printer
  • You want to DOIT three times
  • You want to start with record #1
  • You want to select field #3 through #4

Under these circumstances you would execute DOIT by entering:

The commas (,) are important, so be sure to include them. If you choose not to use a particular option, you must still include the comma. To demonstrate this important use of punctuation, the following example illustrates the execution of DOIT, first echoing the results to the printer and then again without echoing the results (as a training aid, an arrow () has been placed under the "P" which selects this option):

"P" selects echo option

DOIT A:FILENAME.EXT,P,3,1,3,4

Missing "P" eliminates echo option

DOIT A:FILENAME.EXT,,3,1,3,4

Note in both examples that the total number of commas remains the same, only the "P" is affected!

This example merely highlights the general nature of presenting operating instructions. In your documentation you would want to provide greater detail and cover additional items, such as defaults.

Providing a reference section in your documentation can be a real time saver for the experienced user. Rather than having to wade through the operating instruction section again, they can simply turn to the reference section for a quick memory job. Items you may want to consider for inclusion would be:

  • Abbreviated command summary listing with brief description of each command sequence or keystroke
  • Description of special files needed or created by your program
  • List of error messages and remedies.
  • Glossary of unfamiliar words
  • User patches for such things as changing I/O ports, peripherals, etc.

While not actually part of a reference section, an Index and Table of Contents are handy reference tools. Both are used to quickly direct the user to a specific location in the documentation, but they approach their task from opposite directions. The Index is used to locate the desired page when the appropriate keyword is known. The Table of Contents is used when the general function is known but the specific keyword is not known.

Testing is the final, and most critical, part of documentation preparation. During the programming phase you tested all the program's permutations to spot the errors and omissions. This same type of testing needs to be performed on your documentation. However, this testing is better done by someone else. Give a friend a "distribution diskette" and a copy of your documentation. Ask him to go through it just as if he had bought it off the shelf. Have your friend make notes of those areas that were confusing, needed more explanation, or were missing altogether. You might even consider doing this with several friends of differing backgrounds and experience levels. Once your documentation has been thoroughly tested (a day or two for small- to medium-sized programs), review their comments and make the appropriate changes.

Before ending this discussion, there are a few technical points to consider. The vocabulary you use affects overall understandability. Imagine how a new computer user would react to words such as argument, array, operand, string and I/O. Unfamiliar words force your reader to jump extra hurdles of intimidation to master the operation of your software. If you must use potentially unfamiliar words, thoroughly explain them in plain English before thrusting them on your reader. Sentence structure is another factor which has a decided effect on readability. Keep sentences short and use commas sparingly. When tempted to include parenthetical statements using commas, ask yourself if readability would be increased by using two separate sentences instead. And finally, the manner in which explanations are presented affects how quickly they are understood. Consider the following two presentations of identical instructions. Which one seems easier to follow?

THIS?

Place the command disk in drive A and the data disk in drive B. Turn the computer on and allow it to initialize itself. When the computer signals it is ready, type the command: DOIT (and the return key).

OR THIS?

  • Place the command disk in drive A
  • Place the data disk in drive B
  • Turn the computer on and allow it to initialize itself
  • When the computer signals it is ready, type the command:

DOIT (and the return key).

Presenting instructions in checklist format makes them easier to follow for someone who might be executing them "by-the-book."

The type and quality of documentation you provide with your program can greatly enhance its overall attractiveness. Good quality documentation, like good quality programming, does not just happen. It requires thoughtful effort on your part. When approached in a step-by-step manner, producing quality documentation is not an insurmountable task. In fact, it can actually be an exciting part of your overall software production efforts. (P.S. Enjoy the induction ceremony, you deserve it.)