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

Oil Pressure    

Red Light On

Green Light On

Under 40 lb

Loosen R.H. banjo screw

Check ignition element held by L.H. banjo screw

Over 40 lb

Switch off dynamo and wait for green light

 

Tree diagram

Example of a decision tree

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.

Press this key    

To move the cursor

l or <spacebar&gt

Right one character

h

Left one character

$

To end of line

w

Forward to next word or punctuation mark

W

Forward to next word, ignoring punctuation

Example 3: Playscript

(Adapted from Brockman, 1986)

Daily Time Collecting


Actors


    Actions


Executive secretary


  1. Upon receipt of time cards, sort them by department, and place in Summary Envelope.
  2. Deliver to department clerks.

Department clerk


  1. Distribute time cards to all employees.

Employees (all)


  1. Prepare time cards as instructed.
  2. Send to department clerk.

Department clerk


  1. Collect all time cards at end of shift.
  2. Calculate regular time and overtime.
  3. Post totals, with grand total for each job, on Summary Envelope.
  4. Place all time cards for the day in the Summary Envelope, fill in date on the envelope.
  5. Deliver the Summary Envelope to the Human Resources Group by 10:00 am of the following day.

Human Resources Group


  1. Calculate regular time and overtime by job from all departments, then post to Project Expenditure Work Sheet.
  2. Send all time cards to the payroll section of Accounting.
  3. Return Summary Envelope to department clerk to be filed as a permanent record of hours worked.

 


 

Figure 1. Structured writing format (facing pages)

Diagram of structured writing format (facing pages)

Example 4: Structured Writing

(Adapted from Brockman, 1986)


Component


Writing Rule


Overview


A glossary of structured writing terms and two format rules of the structured writing style are presented on this page: the concept of blocks and the use of labels.


Glossary of structured writing terms


  • A page is called a map.
  • A paragraph or closely allied group of paragraphs is called a block.
  • A sentence is called a chunk.
  • A heading is called a label.

Concept of blocks


Present information in visible blocks that are outlined. This makes information bite-sized and localizes all the information on one topic or aspect of that topic in one physical place.


Use of labels


Standardize labels and their locations on the page. Side labels are restricted to the left column and do not cross over into the text column on the right. This type of label allows the reader to read the text uninterruptedly, whereas conventional cross-headings interrupt the text and strongly imply borders. Therefore, use side labels rather than cross labels.

Structured writing’s use of such left-hand column labels coincides with the research that suggest that “the left half of the page has a strong influence on reader attention.” You can speed retrieval of information and improve readability by using such side labels.


Printer-friendly version

Last updated 19 September 2001

Follow me on Twitter  My profile on LinkedIn

Categories

Archives

Follow

Get every new post on this blog delivered to your Inbox.

Join other followers: