Writing Software Documentation

WRITING SOFTWARE DOCUMENTATION

Adapted from Writing Software Documentation: A Task-Oriented Approach,
by Thomas T. Barker

Computer documentation, when done correctly, enhances the value of the software described by making it easier to use and therefore more accessible. Think of the first time that you used a new program. How did you learn it? Chances are that at some point you referred to a manual or used on-line help. It's also likely that some of the support provided may have frustrated you because of its lack of clarity.

Most documentation projects today use a task-oriented approach. Information is presented in chronological order based upon the job being performed. Here is an example from a quick start guide for a Palm Pilot:

Deleting a Note:
1. Select the note you want to delete.
2. Tap Delete.
3. Tap OK.

Tip:
You can also delete a note by
opening it, selecting Delete
Note from the Record menu,
and then tapping OK.

This how-to approach to all forms of computer documentation, including on-line documents with links to related topics and help files that guide even beginning users, has made more sophisticated software accessible to everyone.

The first requirement for task-oriented software documentation is an understanding of the jobs your users perform. Technical writers gather this information by conducting interviews designed to determine what people do and how they do it with an eye on how the software will make their jobs easier. Let's say you were going to write the manual for Microsoft Word. Your programmers have already shown you all the things the software can do. Now it is up to you to provide this information to others.

Because you have interviewed them, you understand the tasks your users perform each day, and you are prepared to show them how all the functions the engineers designed will help make word processing easier. Without the writer, even the best software can remain a mystery to its audience.

There are three types of users. The first is the novice. This user is inexperienced and therefore anxious about learning new applications. It takes novices longer to learn a program, and they do not like vague instructions. For the beginner, tutorials and guided tours are the documentarian's most effective tools. Novices frequently prefer learning from instructors or other users than from a manual.

The experienced user is open to learning in new ways. They see the computer as a tool and are not anxious about mastering new applications. An experienced user is significantly more receptive to manual usage and on-line help and will be willing to be flexible in taking instruction.

The expert user, unlike the other two, understands and cares about how a program works. These users will occasionally refer to the manual and will use on-line help a lot. They will master a program quickly and will grasp many functions with little or no instruction at all.

Now that you understand your user, its time to design tools to help them. Software documentation can take many forms. There are user guides, manuals, tutorials, help systems, quick reference cards and Getting Started sections, often used for installation and set-up, as well as reference guides designed for referral only. For our purposes, we will concentrate on the manual.

When you write software documentation in EG1004, begin with an Introduction. In this section you should explain what the software does, briefly, so that the user has some idea of what to expect. Think of it as a definition of the program. This example is from the manual for a Palm m100 personal digital assistant:

Palm m100 series handhelds will help you get to meetings and appointments on

time, remember people's names and personal details, and track items on your To Do list. You can enter your schedule in Date Book; keep all your contact names, addresses, phone numbers, and other details in Address Book; prioritize and assign your asks a due date in To Do list; and jot quick notes directly on the screen in Notepad. To keep your data extra safe, you can synchronize your data with the Palm Desktop organizer software on your Windows or Macintosh

computer so you always have a backup copy.

Remember, you cannot write a whole manual in one paragraph. Your Introduction is like a highlight reel that will get the reader acclimated. Keep in mind as you write that readers of manuals often skip the paragraphs and go on to the instructions. To avoid this, keep it short. Paragraphs work best when they support simple concepts, such as a definition of terms, but they must read quickly and easily.

Following your introduction will be the procedures section. You will begin with a scenario, and then provide step-by-step instructions. We will use a standard format. It consists of steps, notes, screens and other elements aligned on the left margin and continuing in a single column in a numbered sequence from first step to last.

A scenario reminds the user what the task about to be described will help him accomplish. It has the dual function of introducing the task and suggesting workplace applications. The scenario should set the user up to perform the steps. Here are a few examples of scenarios:

You can use the Display command on the Options menu to change the colors in the MSDOS Editor window, display or hide scroll bars, and set tabs.

You can remove programs that you don't want to appear in the Scan to Application window, or change the default format for each program's files.

The edit menu is available with any screen where you enter or edit text.

In general, commands available in the Edit menu apply to text that you select in an

application.

The procedure section describes step-by-step what you want the user to do. They are typically numbered lists of instructions that follow chronologically with as little digression as possible. This example is from the manual for an Epson Stylus Scan 2500:

Removing and installing ink cartridges:

1. Remove the new ink cartridge from its package.
2. Remove only the yellow part of the tape seal on top. Don't pull off the blue portion or try to remove the clear seal underneath the cartridge.
3. Make sure the EPSON Stylus Scan is turned on and not printing. Open the document cover, and then open the maintenance cover. The internal cover opens automatically.
4. Press the cleaning button and hold it for about three seconds until the print head moves left and the Operate light begins flashing.
5. Pull up the ink cartridge clamp. The cartridge rises up from its holder.
6. Lift the cartridge out of the EPSON Stylus Scan and dispose of it carefully.
7. Lower the new ink cartridge into its holder with the label facing up and toward the back of the printer. Don't press down on the cartridge.
8. Press down the ink cartridge clamp until it locks in place.
9. If you need to replace the other ink cartridge, repeat the preceding steps before going on to Step 10.
10. Close the maintenance and document covers, and then press the cleaning button.

Here are a few guidelines to keep in mind as you begin your writing. Focus on actions rather than functions. Talk about what the user will do, not how the program will work. Unlike the style we employ in Lab Reports, in Software Documentation use the active voice.

Incorrect:

The File menu can be used to […]

Correct:
You can use the File menu to […]

Remember, simplicity helps in every aspect of software manual writing. This cannot be over emphasized. If your writing is clear and direct, your manual will be easier to use. The tone you adopt should not be overly formal. The manual you write should sound conversational. Pretend you are talking your user through the software. However, do not go overboard and forget the importance of correct grammar and syntax. And do not forget to use articles.

Software documentation is increasing handled by technical professionals. Mastering these skills will make you more employable. Even if you are never called upon to actually perform the task, you will work with others who do. Your understanding of their objectives will make you a better colleague.

Return to Table of Contents

Continue to next topic: Instructions for Preparing your Final Proposal Cover Letter

Continue to previous topic: Graphics in Technical Reports