Convert Some Paragraphs into Playscripts

Playscript is a technique used to render a great range of instructions, specifications, and procedures into readable tables.

Before:

To get access to the files of another user on the LAN, you must get the owner of the files to grant written permission, specifying your read/write privileges on Form MIS89–10. This form must be sent to the LAN Administrator who, after receiving the form, has 5 days to create the software links necessary, consistent

User Menu Select . . .

New User Maintenance Setup

User wanting to

change preferences Maintenance Setup

Other users File New (new file)

OR

Open (existing file)

with the read/write privileges. (For read-only links, the LAN Administrator must respond within 3 days.) Upon receipt of an e-mail bulletin from the Administrator, you may access the designated files.

After:

Actor Action

Applicant 1. Tells file owner of access request 2. Completes form MIS89-10

2a. If denied, advises applicant LAN Administrator 3. Creates necessary software link

3a. If read/write, within 5 days 3b. If read-only, within 3 days Applicant 4. Sends e-mail bulletin to applicant

5. Accesses the file, as needed Tactic 47: Convert Some Paragraphs into Decision Tables

To save space, technical communicators will often compress a branch-ing procedure into a sbranch-ingle paragraph. The followbranch-ing example shows how much easier such a paragraph is to understand in the form of a tree diagram.

Before:

You can create new subjects just as you create new collec-tions by clicking Subject on the Opcollec-tions menu, then access-ing File menu. You can also move subjects from one collection to another by dragging them to the new collection, or you can delete subjects from MM Manager by highlighting the subject and clicking Delete on the Edit menu.

After:

Create Select Follow

new NEW instructions

subject

Run MM OPTIONS Move Highlight Drag to

Manager Menu: subject? subject another

Select collection

SUBJECT

Delete Highlight EDIT Menu:

subject subject DELETE

When text includes procedures, decision rules, and even branching paths, there are many other diagramming options as well. The following illustration shows the conversion of a paragraph into what is called a logic box, a graphical alternative to the decision tree, rendered more easily in a word processor.

Before:

If you receive the “Illegal Access Attempt” message, deter-mine whether you have mistyped the name of the file. (If you have, retype and continue.) If the file name has been typed correctly, review your access privileges by pressing <PF18>

(or Alt+F8 if you are using a PC as a terminal). If you are denied access, you must contact the DB administrator to get your privileges changed. If you are not denied access, call the Help Desk for consultation.

After:

Assure that the file name is typed correctly; then . . . AND IF

IF you THEN you receive THEN you

are using press the message should

A PC- ALT + F8 Denied Call DB

terminal administrator

Not denied Call help desk

A standard PF18 Denied Call DB

terminal administrator

Not denied Call help desk Tactic 48: Convert Some Paragraphs into Logic Diagrams

An especially useful diagramming technique, the Nassi-Shneiderman chart, was developed in the 1970s as a flow-charting method for soft-ware engineers. It also works well to explain a wide variety of human and manual processes that involve decisions or iterations.

Before:

Defining the Category of Failure

The Manager of the Failure Analysis Laboratory determines the class of the failure, marks the sticker, and prepares a task document. In the case of bad subassemblies, he/she meets

with either the apposite DIGISOUND function or subcontractor.

(No such meeting is required for defective contacts.) If the fail-ure is from neither subassemblies, contacts, nor handling prob-lems, the manager develops a High-Level Analysis Plan.

After:

See Weiss, Edmond, “Visualizing a Procedure with Nassi-Shneiderman Charts,” Journal of Technical Writing and Communication, Vol. 20(3): 1990.

Reducing Burdens as an Ethical Objective

Removing unnecessary burdens is an act of unselfishness, an extra exer-tion by the writer for the benefit of the reader. Granted, many of these extra exertions are meant to be a form of enlightened self-interest or deferred gratification. The rewards are downstream a bit. Even so, my experience is that the writers most likely to take time and pains with their work, to make the extra editorial sweep or two through the text, are those who genuinely care for their readers and who want them to have the easiest reading experience possible.

Caring about the reader is a difficult emotion to counterfeit, as is seeming to be sincerely interested in another country when your motive is obviously short-term profit. Good communicating, as Quintilian once observed, needs good people.

Discussion Questions

• Do you find yourself skimming nearly everything you read? Does this prevent you from getting what you need from the documents?

What might prevent you from skimming?

• In your school or business reading, have you ever noticed differ-ences in the style of the writers you must read: specifically, that some seemed unnecessarily harder to read than others, even though they were writing about similar matters?

• In your school or business reading, have you ever noticed differ-ences in the layout and organization of textbooks and other docu-ments: specifically, that some seemed unnecessarily harder to use than others?

• When you have difficulty following written instructions, do you tend to blame yourself or the writer?

• When you prepare longer documents—reports, proposals, manu-als, and so on—do you worry about where the pages break? where the figures and tables appear in relation to the text that discussed them?

• Acquire and read a copy of the Security & Exchange Commission’s Plain English Handbook (www.sec.gov/pdf/handbook.pdf). Do you believe all financial and business documents should follow this guide? Is anything in this guide unsuitable for International English?

Sources and Resources

Andrews, Deborah C. (ed.). International Dimensions of Technical Communica-tion. Arlington, VA: Society for Technical Communication, 1996.

Andrews, D. C. Technical Communication in the Global Community. Upper Saddle River, NJ: Prentice-Hall, 1998.

Barzun, Jacques. Simple and Direct: A Rhetoric for Writers. Revised ed. Chicago:

University of Chicago Press, 1985.

Brockmann, R. John. Writing Better Computer User Documentation: From Paper to Hypertext. Version 2.0. New York: John Wiley & Sons, 1990.

Casady, Mona, and Lynn Wasson. “Written Communication Skills of International Business Persons.” The Bulletin of ABC 57, no. 4 (1994) 36–40.

Garbl’s Grammar Webpage (http://garbl.home.comcast.net/writing/grammar.htm) Hoft, Nancy L. International Technical Communication: How to Export

Informa-tion about High Technology. New York: John Wiley & Sons, 1995.

(Nancy Hoft’s website, http://www.world-ready.com, may be the best single resource for students of international communication.)

Horn, Robert E. Visual Language: Global Communication for the 21st Century.

Bainbridge Island, WA: MacroVU Press, 1998.

Huckin, Thomas N., and Leslie A. Olsen. Technical and Professional Communica-tion for Nonnative Speakers of English. 2nd ed. Boston: McGraw-Hill, 1991.

Jones, Scott, Cynthia Kennelly, Claudia Mueller, Marcia Sweezey, Bill Thomas, and Lydia Velez. Digital Guide to Developing International User Information.

Maynard, MA: Digital Press, 1992.

Kohl, John R. “Using ‘Syntactic Clues’ to Enhance Readability for Nonnative Speak-ers of English.” Society for Technical Communication, Proceedings of the 38th Annual Conference (1991) 54–571.

Menand, Louis. “Bad Comma.” The New Yorker, June 28, 2004, p. 103.

Nielsen, Jakob, and Marie Tahir. Homepage Usability: 50 Websites Deconstructed.

Indianapolis, IN: New Riders Publishing, 2001.

Schriver, Karen A. Dynamics in Document Design. New York: John Wiley & Sons, 1997.

Victor, David A. “Advancing Research in International Business Communication.”

The Bulletin of ABC, 57, no. 3 (1994) 41–42.

Ward, James. “Editing in a Bilingual, Bicultural Context.” Journal of Technical Writing and Communication 18, no. 39 (1988) 221–226.

Weiss, Edmond. How to Write Usable User Documentation. 2nd ed. Scottsdale, AZ: Greenwood/Oryx Press, 1991.

93

5