Alternatives to the paragraph

by Jean Weber

Keyword 1 (1), August 1989, pp. 14-16. (Journal of the Australian Society for Technical Communication (NSW) Inc.)

“It’s all in the manual.”

How many times have you heard that – or said it in frustration? After all, when you are the person who wrote the manual, you know that all the answers are there. But time and again readers can’t find what they need to know, or don’t understand the material.

Before you blame the reader, look again at how you’ve presented the material.

Remember that different people respond to different presentations. Not everybody gets information easily from ordinary sentences and paragraphs – even well-written ones.

Some instructions are easier for many people to follow if you throw away those sentences and paragraphs completely for awhile, and use

• bulletted lists
• tables or matrices
• diagrams
• flowcharts or logic trees
• pictures and graphics
• playscripts
• structured writing

Deciding which style is best for a given situation isn’t always easy. Sometimes you’ll just have to write the same material in two or three ways and test the results on somebody unfamiliar with the product or system you’re writing about.

Most of these presentation styles, except perhaps for playscripts and structured writing, should be familiar to you, so I won’t discuss them in detail here. See Examples 1 and 2 for a comparison of different ways of presenting the same material.

Playscripts

The playscript is used mainly for procedures manuals. It integrates the activities of a number of people involved in one project. It is written in the who-does-what-when arrangement, using a two-column format. This allows readers to skim and scan easily. Example 3 is adapted from Brockman (1986).

Structured writing

There are several variations on this theme, but they all use the following ideas:

1. Break information into “chunks” that will fit on a single page, or on two facing pages.
2. Use headlines and subheads to guide the reader in skimming and scanning.
3. At the top of the page, give an overview of the main idea covered in that page.
4. Place the steps in order. Do not require the reader to jump forward or back to find necessary information. Repeat yourself if necessary.
5. Use action words, the present tense, “plain English” and short sentences.
6. Use alternatives to paragraphs, as described earlier. If you do use paragraphs, keep them short.
7. Use plenty of white space.
8. Present information from the reader’s point of view.
9. Indicate a practical reason for information.
10. Present similar topics in a similar way; that is, be consistent in style and presentation.

Figure 1 shows the format of two facing pages. Example 4 is adapted from Brockman (1986).

Reference

R. John Brockman. Writing Better Computer User Documentation. New York: John Wiley & Sons, 1986. Part 2, Step 2, has an extensive bibliography on this subject.

Jean Weber has 15 years experience in scientific writing, editing and publishing with CSIRO, other research organisations and industry.

Example 1

(Adapted from Brockman, 1986)

This example shows four ways of presenting the same material. Standard prose is difficult to follow, but which of the other presentations you select will depend on the way the information is to be used, and by whom.

Standard prose

Loosen the right-hand banjo screw whenever the red light comes on, unless the oil pressure gauge reads over forty pounds per square inch in which case switch off the auxiliary dynamo and wait for the green light before proceeding to check the ignition element held by the left-hand banjo screw.

Table

Procedure when red light comes on

    If oil pressure under 40 lb

        loosen the banjo screw

    If oil pressure over 40 lb

        1. Switch off dynamo

        2. Wait for green light

        3. Check ignition element

held by L.H. banjo screw

Matrix

Tree diagram

Example 2

Example 2 is taken from actual material that I’ve edited. I leave it to you to devise an even better way to present it.

Before

Vi can be confusing because there are three possible modes of operation when you are typing. You can be typing material into your text. You can be typing a command to manipulate your text. You can be typing a command that will appear on the bottom line of your terminal. The same keys can have vastly different effects, depending upon which mode you happen to be in at the time. Therefore, you must remain aware of which mode you are using. This concept will be covered in detail later.

Moving the cursor

Either l or the <spacebar> will move the cursor one space to the right. The $ key will move the cursor to the end of the line. The w key will move the cursor forward to the next word, or to the next punctuation mark, while the W key moves you to the next word, and ignores any punctuation. {This style of paragraph continues for three pages.}

After

Vi can be confusing because there are three possible modes of operation:

• You can be typing material into your text
• You can be typing a command to manipulate your text.
• You can be typing a command that will appear on the bottom line of your terminal.

The keys can have vastly different effects in each of these modes. Therefore, you must remain aware of which mode you are using. This concept will be covered in detail later.

Example 3: Playscript

(Adapted from Brockman, 1986)

Daily Time Collecting

Figure 1. Structured writing format (facing pages)

Example 4: Structured Writing

(Adapted from Brockman, 1986)

Printer-friendly version

Last updated 19 September 2001