Chapter 15 of Houp/Pearsall/Tebeaux's Reporting Technical Information, 9th ed. (New York: Allyn & Bacon, 1997) presents strategies and format for developing instructions. Accompanying the textbook, this chapter of the online instructor manual provides the following:
|
table of contents. |
- Understand the purposes and uses of instructions.
- Understand how lack of audience analysis and adaptation can cause problems in instructions.
- Know the typical contents and organization of instructions.
- Understand the role of background and theory in instructions.
- Know how to use headings, lists, warnings, and graphics in instructions.
- Understand how to test instructions on the target audience.
- Know how to review and critique a set of instructions based on the concepts presented in the chapter.
Instructions should be a key component in any technical writing course. Most of the critical issues involving process, audience, graphics, format, and writing style are immediately relevant to instructions. Also, students typically get quite energetic about studying and writing instructions. Like most of us, they've experienced poorly written instructions and have felt that they could certainly do better. In fact, more than a few professional technical writers have begun their careers just this way—"I can do better than this!"Students usually feel very confident writing instructions—after all, they've read lots of them. For that and other reasons, the instructions unit is a good one in which to introduce key formatting issues including:
Call students' attention to the way these special formatting elements make instructions more scannable, readable, and retrievable.
- headings
- lists
- warnings
- graphics
One note of warning, however. If you let your students design their own headings, lists, and warnings, you're in for an interesting array of page-design ideas. You'll have to critique each on its own merits, which will add considerably to your workload. Instead, provide your students with some minimal specifications for the design of the headings, lists, and warnings. You can hand out "spec sheets" which show students exactly how you want headings to be designed—in terms of bold, italics, margins, indentation, fonts, and stylistic issues (such as parallelism, stacked and lone heads, and so on). You can specify when to use bulleted as opposed to numbered lists, how to capitalize and punctuate list items, and how to approach stylistic issues such as parallelism. (See the example specifications sheet in chapter 8 of this instructor's manual.)
Both the workshop and projects sections in the following mention usability testing. If you are not familiar with it, usability testing is a method of testing products and their documents on the intended users. Usability-test experts bring in people who are representative of the customers for whom a product is intended and then have them use the product and its documentation in carefully designed ways to uncover potential problems. Usability testing is a highly professionalized field, complete with theory, methodology, degrees, journals, and international conferences. However, you can have your students conduct mock usability tests right in your own classroom. Have students design test scenarios for each other's instructions (but not for their own). Have another student perform the actual tasks in the test scenario while the writer and tester watch and take notes. Students will be amazed at how much can go wrong in even the simplest instructions. An excellent resource on this field and its methodologies is Jeffrey Rubin's Handbook of Usability Testing (New York: Wiley, 1994).
Here are some ideas for things you can do in class to help students learn about instructions and get ready to write their own:
- Give the initial quiz. Try giving the quiz at the beginning of this unit. It's a good springboard into discussion of key aspects of instructions. When students have completed the quiz, you can go through the answers with them as a group, which will open up the discussion to the broader issues in the chapter.
- Review key concepts. Using the chapter point summaries contained in this section of the instructor's manual, review the key concepts involving instructions.
- Provide or review guidelines on headings, lists, and notices. Consider providing students with specifications on headings, lists, and notices as well as highlighting (bold, italics, caps, fonts). Your students have probably never used format like this before; they'll want some guidelines to start with. If students create their own individual designs for these elements, you may be in for some headaches critiquing the wide variety of formats they will produce. (See the example specifications sheet in chapter 8 of this instructor's manual.)
- Apply the instructions checklists. A good classroom exercise is to use the instructions checklist at the end of the chapter to analyze the example instructions shown in the chapter. Students tend not to read the examples carefully and thus are not clear on the details of the contents, organization, and format of instructions. Also, students tend not to use these helpful checklists when they are completing their own drafts and thus forget to include certain key components of instructions. Applying the checklists to the examples in the book may help in both these areas.
- Show-and-tell instructions. Have students bring in instructions that they find notable, either for their effectiveness or, more likely, for their problems, and then present them to the class. If you are just starting out as a technical writing teacher, this is a good way for you to build your own files of good and bad examples of instructions.
- Group-revise poorly written instructions. Find or create a poorly written set of instructions to group-revise with your students during class. Better still is to wheel a computer and projector into your classroom, and have students tell you what to change in the actual file.
- Unscramble scrambled instructions text. Another classroom possibility is to take the text of a good set of instructions, scramble the sections moderately, and then retype that text as one huge paragraph without any other formatting. Get the class discuss how to rearrange the text and format it. Have some fun with this—get students to bring scissors and tape to class. Or you can bring in a computer and projector into your classroom, and have students tell you how to edit the scrambled text.
- Plan and write simple instructions in class. Demonstrate a simple procedure in class (for example, tying a tie or changing the lamp on the overhead projector). Have students take notes and discuss how to write instructions on that procedure. If it's part of your course plan, have them plan the headings, lists, warnings, and graphics. You probably won't have time to write the entire procedure with the class, but make students volunteer the structure and as much text as they can. Get a good start on some of the representative sections and let them complete these instructions by next class meeting. (This one also works well with a computer and projector in the classroom.)
- Usability-test a brief set of instructions. An excellent classroom activity is to engineer a mock usability test of instructions that you know have problems. Students can break up into teams of test administrators, test observers, and test subjects (the ones who have to perform the test tasks).
The following links show you some examples of the kinds of writing discussed in this chapter. These examples are "annotated": explanatory notes are linked to specific points in the examples so that you can see the relation to the concepts discussed in the chapter. You'll need a browser that supports frames, however.
Here are some discussion questions related to this chapter:Situational Analysis for Instructions (pages 492-494)
- What kinds of situations and audiences call for instructions? How widely do these vary?
- What are some of the ways in which you can alter instructions for readers with different needs and different skill levels?
- How would you adapt instructions so that they meet the needs of readers with a wide range of skill levels and needs?
Possible Components for Instructions (pages 494-517)
- In what ways does document design support readers of instructions?
- What principles govern the inclusion of graphics elements? Where should these be placed?
- Warnings can become the legal responsibility of technical communicators. Why are they important, and where should they be placed? How can document design support effective warnings?
Accessible Format (pages 517-524)
- Why are reader checks important for effective instructions? What are some of the elements which authors can typically overlook and which readers can catch and correct?
- How do readers see, read, and use instructions? How are these patterns different from the way in which readers see, read, and use reports? Letters? How can format and design best meet instruction reader needs?
The following are some suggestions for journal entries related to this chapter:Situational Analysis for Instructions (pages 492-494)
- In what situations do you use instructions? How do you use them? What kind of instructions do you find most helpful for your needs? Why?
Possible Components for Instructions (pages 494-517)
- What kinds of components for instructions do you look for when you want to learn a procedure?
- What kinds do you want in instructions that you want to follow once?
- What kinds of components help you in looking up and using instructions in a book-length manual?
Accessible Format (pages 517-524)
- What elements make the version of the document on pages 522-523 more usable than the version on pages 520-521?
You can structure the instructions assignment a number of ways, depending on your sense of your students' level of ability and your own preferences. Here are some ideas, including ones for collaborative projects:As noted in some of these ideas for writing projects, you can half-write the instructions together with students during the classroom session. In other words, you can get them started in class, which will give them a better idea about what to do when they are writing on their own. This approach works particularly well with less-confident, less-experienced student writers.
- Simple instructions. If your students are more on the basic end of the spectrum or if you want to save their energies for other writing projects, you can have them do a simple set of instructions. The procedure can be a simple one; special effects such as headings, lists, warnings, and graphics can be omitted. The main focus can be careful audience adaptation and clear, economical writing style. This is a good one for an in-class writing exercise, especially if you want to confirm that students' out-of-class writing style is their own.
To turn this into a collaborative project, suggest that student teams organize themselves into these roles:
- Manager. Selects and defines the procedure to demonstrate, assigns roles, establishes meetings, sets a timeline for activities.
- Director. Outlines a script for the presentation, assigns different roles in the demonstration.
- Content expert. Tests the script for completeness.
- Equipment manager. Lists the needed equipment, provides it for the demonstration, packs, and returns it after the demonstration.
- Team members. Each takes part in the demonstration, scripting, or cleanup.
- In-class procedure demonstration. You can demonstrate how to perform a simple procedure (tying shoes, tying a tie, changing the lamp in an overhead projector, or performing some computer task), discuss how to write that procedure, and have students write the instructions either in or outside of class. Either you can do the demonstration yourself, or you can get your students to figure it out. You can make this a relatively simple writing project, such as is discussed in the preceding workshop activity, or you can include the more challenging elements involving headings, lists, warnings, and graphics.
To turn this into a collaborative project, suggest that student teams organize themselves into these roles:
- Manager. Selects and defines the procedure to be documented, assigns roles, calls meetings, establishes a timeline for activities.
- Content Expert. Provides information about the procedure.
- User Advocate. Defines the readers of the procedure, their level of expertise, and their needs.
- Author. Drafts the procedure from the information provided by the content specialist and the user advocate.
- Designer. Makes suggestions about appropriate document design for the procedure.
- Graphics Specialist. Designs and makes suggestions about the need and placement of graphics.
- Editor. Incorporates graphics and design elements into the procedure.
- Usability Expert. Tests the document to make sure that its intended audience can in fact use it..
- Proofreader. Checks the final draft for correctness and consistency.
- Evaluation manager. Supervises the evaluation of the demonstration by the class, summarizes findings, leads the group in a discussion of their planning and performance.
- Out-of-class instructions project. And of course you can have your students write a fully developed set of instructions including elements such as headings, lists, warnings, and graphics. Consider stipulating in the assignment that another student must be able to test-perform the steps in these instructions. (Consider having the student tester write a memo recommending changes to resolve any usability problems found in the instructions and requiring the student writer to revise according to those recommendations.)
The following cases draw upon the concepts and strategies presented in this chapter:
The following point summaries focus on key points in this chapter of Houp/Pearsall/Tebeaux's Reporting Technical Information:
SITUATION ANALYSIS FOR INSTRUCTIONS |
|
COMPONENTS OF INSTRUCTIONS |
Introduction |
The following provides ideas for writing assignments related to this chapter of Houp/Pearsall/Tebeaux's Reporting Technical Information:
|
Assignment: Without using sources, write a complete set of
instructions on a subject you are familiar with to meet the needs of a
specific audience.
Audience: Write for readers with very specific needs, defining their previous level of knowledge carefully. Goals: To provide a complete and accurate set of instructions which your reader can follow and execute. A procedure is a series of causally related steps that lead to a specific outcome. Your reader must understand the steps and their purpose to be able to perform or follow the process after reading it. Introduction and Procedure: Begin by defining the procedure and by explaining its purpose. Then break the process down into a series of related steps. Don't leave out any necessary warnings. If you're writing for beginners, avoid complex technical terms unless you define them. Use headings to organize related groups of steps. Telegraphic Style: Write clearly, in paragraphs or steps. Avoid telegraphic style which leaves out "a," "an," "the," and "it." Telegraphic style makes writing choppy and hard to read. Conclusion: After you have discussed all of the steps in order, close your process with a brief discussion of the completed outcome. If you are writing to teach your reader how to perform a process, be sure to include a way for the reader to test for success in completing that process. Hints:
|
Write a set of instructions in which you explain to a specific
audience how to perform a procedure. Use these guidelines:
Note: As with all writing assignments in this course, keep a safe copy of this one in case something happens to the one you hand in. |