Unit 9 Writing Clear Instructions

9.1 Creating Rhetorically Effective Instruction Manuals

Instruction Manuals

Many people associate instruction manuals with appliances, computer accessories, and products that require assembly (e.g., furniture). Because we don’t find ourselves using them regularly or we come to expect them only in certain contexts, it is easy to forget how important they are. The quality of a well-designed instruction manual may go unnoticed. Yet, when we encounter frustration with putting together a bookshelf or toy, or with trying to figure out how to change or activate a particular appliance setting, the significance of a well-designed instruction manual becomes clear.

Understanding the Rhetorical Situation of Instruction Manuals

Instruction manuals, like other types of texts, are shaped by a rhetorical situation. The choices technical writers make in regards to content and form depend on the purpose of the instruction manual, the intended audience, and the context in which the manual is used. When writing your own instruction manual, consider the following ideas and questions regarding the rhetorical situation.

Purpose

In general, the purpose of an instruction manual is to familiarize the user with the product and/or to guide the user through a series of steps that lead to the completion of a task. However, each instruction manual will also have a more specific outcome. Identifying what that specific outcome is will help you make more effective rhetorical decisions about content and design. Ask yourself:

• What are the specific intended outcome(s) of the instructions? (e.g., baking a cake from scratch, installing an air conditioner, etc.)
• In addition to helping users reach the main desired outcome(s), are there other purposes that the manual serves? (e.g., offering troubleshooting advice, teaching users how to accomplish additional, simple tasks necessary for reaching the main objective)

Audience

Creating a profile of your audience (i.e. the primary intended user of the document) is integral for making thoughtful choices about scope, content, and design. Consider these questions about audience before writing:

• What is the audience’s familiarity or expertise regarding the topic of the instruction manual?
• What is the audience’s general comfort level with learning new skills related to the software, apps, recipes, etc.?
• What is your audience’s “typical” approach to learning? How will your instruction manual address the audience’s learning style, goals, and task-related needs?

Context

Think of context as the temporal, social, technological, and cultural situation surrounding the creation and use of the instruction manual. The following questions will help you identify the context:

• How much time will you have to complete this instruction manual?
• Are there time constraints on the user?
• What technological constraints must you consider in creating the instruction manual? Consider your skills with technology and level of access.
• How will your audience gain access to the manual? (e.g., audience can access manual online via a company website)
• What additional tools or materials are you assuming the audience already has? Will they have access to the technology or materials needed to follow the instructions? (e.g., to successfully build a bookshelf, the user will need a hammer, screwdriver, and open work area)
• From what cultural perspective are you writing the instruction manual? Will the audience share this same cultural context? (e.g., a German recipe that calls for vanilla sugar, an ingredient not readily available in the United States, may need to be modified for American users)

Using Knowledge of Rhetorical Situation to Make Effective Rhetorical Choices

Though most instruction manuals rely upon some standard conventions, each instruction manual should be tailored to achieve a specific purpose for a particular audience within a given context. The following section introduces some common characteristics of instruction manuals, while also taking into consideration the rhetorical situation and how it may require deviation from certain conventions.

Scope

The rhetorical situation helps determine the amount of detail to include in an instruction manual. For example, the scope of an instruction manual for assembling a desk is easy to determine because it has only one outcome: putting together the desk. However, an instruction manual for a Digital Single Lens Reflex (DSLR) Camera may be written for both amateur and more experienced camera users and may need to include instructions for completing basic tasks (e.g., installing the battery and memory card) as well as more advanced tasks (e.g., adjusting settings for specific shooting environments).

Content

Some standard sections of instruction manuals include front matter, an introduction, a series of steps, a conclusion, and back matter, though some manuals may not use all of these sections or label them in this way. Extensive front and back matter, for example, are often found in longer, more complex manuals. Most sets of instructions, however, contain an introduction that provides information necessary for completing the steps safely and efficiently. The introduction may include an explanation of who should carry out the task (maybe the user needs to have proficiency in a certain skill), the materials needed, any precautions that the user should take (safety tips or other warnings), and in some cases, an estimate for how long the process will take (a common feature of recipes). In some cases, it is necessary to include an explanation of why the user should follow the instructions. For example, instructions for changing the oil in a car may explain why the task is necessary for the proper functioning of the vehicle.

Following this introductory material is the sequence of step-by-step instructions. See the following section on “Language” for how to draft clear and effective steps. Lastly, an instruction manual may include a “Troubleshooting Guide” or a section for “Tips” to help users address common problems that they may encounter while following the instructions or after completing the process.

Language

The questions about “Audience” and “Context” above can help guide you in making effective language choices. The following subsections include explanations of common linguistic features of instruction manuals along with tips for writing clearly and concisely in this genre.

Imperative mood

Instructions, like commands, often utilize the imperative mood. To write in this way, address the audience directly using active voice and specific verbs. Which of the following provides the clearest instructional step?

• “Press the red button to begin playing the game”
• “When the red button is pressed, the game will begin”
• “The operator should press the button”

Though a user could probably make sense of any of these sentences, the first one provides the clearest explanation of what action should be performed by the user. The second, passive construction does not specify who should press the button. The third example refers to a vague subject, the “operator,” which may confuse the user.

Word Choice

When writing instructions, a careful consideration of word choice is important because in some cases, the user’s safety is at risk. For this reason, strive for clarity and conciseness. To make effective decisions about word choice, consider your primary audience’s level of expertise and cultural background. You may find it necessary to

• define complex terms.
• spell out acronyms the first time they are introduced (e.g., digital single-lens reflex camera, DSLR).
• avoid using similes, metaphors, slang, or substitutions that may confuse users.
• use plain language, for in some cases, serious legal consequences can arise when a set of instructions is unclear. For more on plain language, see https://www.plainlanguage.gov/index.cfm
• include translations of the instructions into multiple languages.
• use brief and informative headings and subheadings

Consistency and Parallelism

Parallel structure, or parallelism, means using the same grammatical structure to present information or ideas. Parallelism is often used to improve readability and create consistency.

This numerical list of instructions contains a step that breaks parallel structure. Which of these steps seems different from the others?

1. Remove the screw to open the battery compartment.
2. Insert batteries by following the image on the battery compartment.
3. Now you may close the compartment, and screw it closed.

Step three breaks the parallel structure of the list because it does not start with a directive verb.

Do the following headings use parallel structure? Why or why not?

• “Installing batteries”
• “Turning device off/on”
• “How to charge your device”

Design

Document design refers to the way information is organized and presented. Because visuals require less time to process, users will typically notice—and respond to—quality of design before quality of content. Even if you choose not to include images or graphics, you will need consider design. Minimally, this includes making choices about layout, order of information, font size, typeface, headings, color, and white space. Design elements should guide the user through the manual smoothly. This means making the document scannable; a scannable document allows users to navigate through the content to locate specific information. As with any document, decisions regarding design should consider the audience, purpose, and overall ease of use.

Consistency/Repetition

Using a design element in a uniform way throughout the entire document guides users by giving them a sense of what to expect (e.g., the same typeface and size for all headings; the same layout from page to page).

Contrast

Using a design element to highlight specific information or features of the manual (e.g., capitalizing a word for emphasis; placing a box or border around an item; changing colors for emphasis). Contrast is primarily effective when a document uses consistency overall. If there is a lack of consistency, it is more difficult to create contrast.

Alignment

Organizing items on a page with horizontal and/or vertical alignment creates hierarchy and structure, and can be used to help achieve balance, contrast, or consistency. For example, this document uses vertical alignment to create a hierarchy between the name of a design element, which is left aligned, and its description, which is indented.

Balance

Distributing items evenly across a given space. To achieve this, each item’s weight–that is, the tendency of the eye to gravitate toward an item–should be considered. For example, since an image weighs more than text, decisions about image placement should consider how to balance its weight against other items in order to prevent visual confusion.

White Space

Using white space to create a professional, balanced document. Rather than indicating the color of the space, this design element refers to an absence of images and text. White space helps distinguish between individual items and groups of items (i.e., sections of the manual) and makes scanning documents easier.

Grouping/Proximity

Placing related images or content close to one another. For example, grouping together images of all the materials needed to complete the given task.

Color

Selecting colors to create contrast and emphasis, to guide readers across space, and to design a visually pleasing document. You should consider the document overall in order to create a consistent color scheme. For example, if you want to use blue in your document, you will want to ensure that it is used consistently and complements other document colors.  This is particularly important when integrating color graphics and/or images.

Images

Choosing appropriate images for the given context and purpose of the manual.  You should consider whether the images are intended to stand alone or to supplement written instructions. Consider types of images, such as drawings, photos, and graphic illustrations and whether any additional callouts or annotations are needed to highlight specific parts of the image. Images should be chosen to complement other design elements in the manual.

Conclusion

A good instruction manual begins with careful consideration of the rhetorical situation–purpose, audience, and context. This information is key for making both appropriate and effective choices about content, language, and design. In an ideal timeline, technical writers have the opportunity to conduct usability tests, which are designed to assess how well a document fulfills its purpose. Once your instruction manual is tested, you’ll incorporate the feedback received to finalize its design and content.

Exercise 1 – Familiarize yourself with instruction manuals

The following website contains several examples of open-source instruction manuals. Follow this link, browse through the list, and choose one manual to look at in depth. Skim through the manual to familiarize yourself with its content and design. Then, in a memo to your instructor or classmates, address the following.

Identify the rhetorical situation

• Who is the audience? How do you know who the audience is? What can you assume about the audience based on the content and design choices in the manual?
• What is the purpose of the document? How do you know this is the primary purpose (i.e., what content and design choices signal the purpose)?
• What context informs the written content and design of this manual?

Examine composition choices

• Describe the overall scope and organization of the manual. How detailed is the manual? What does it cover? How is the information organized?
• Are all the “standard features” of content covered in this manual? Why or why not? Are there additional features? What are they and what are their purpose(s)?
• Locate and describe examples of effective language choice. Explain why you find them effective.
• Locate and describe examples of effective design. Explain why you find them effective.
• If you were the author of this manual, what would you have done differently and why?

Exercise 2 – Planning an instruction manual

Imagine you are writing an instruction manual for a process or product you are familiar with and address the following prompts.

Identify the rhetorical situation

• Select an audience and create a 2-3 sentence profile statement
• identify the specific purpose of your instruction manual
• List any important contextual information to consider

Create a plan

• List the sections you will include
• Identify the most important factors to consider for your audience and purpose (e.g., language use, incorporation of images, text size, etc.)
• Create a sketch that shows the document layout, identifies location of written sections, and shows where images would be incorporated.

9.2 Instructions & Process Reports

“How is this done? How can I do this?”– These questions guide authors as they describe processes. Learn how to write instructions and processes so that readers know how to do something or understand how something is done. By viewing sample process texts, note the focus on the objective voice, numbered steps, visual rhetoric, and clever animations or video. Write a descriptive or prescriptive process report.

There are three types of process texts:

1. Descriptive processes answer “How is this done?” These texts describe how a process occurs so that readers can understand it better.
2. Prescriptive processes are instructions; they explain “How can I do this?” In other words, they prescribe how something should be done so that readers can do it.
3. Blended descriptive and prescriptive processes make the main thrust of the document a descriptive process while having a few call-out boxes summarizing how the readers can perform the process. In other words, writers may address both “How can I do this?” and “How is this done?” in different parts of one text. Alternatively, they might develop different versions of the same document for two audiences–an audience of users and an audience of interested parties.

Why Write About Processes?

Process texts are extremely common in school and professions. In school, teachers frequently assign process assignments. For example, humanities professors may ask for a description of how an artistic or literary period evolved; history professors, the contributions of a culture’s leaders over time; social science professors, the chronology of inventions; engineering professors, explanations of how sound is changed into electrical signals; business professors, how the Federal Reserve works or how to sell a product.

On a daily basis, we read descriptive processes. Intelligent people are inquisitive; they want to understand how things work. Last year, for example, over three million readers a month accessed How Stuff Works, a Web site containing thousands of process essays. We routinely read processes, including recipes, user manuals for new software, or advice columns on how to lose weight or how to succeed in school or a profession. People are always wondering about things, wondering how computers work, how grass grows, how heart disease occurs, how far the human eye can see, and so on.
Instructions: Use the sections below, as directed by your instructor, to learn about writing processes. Read sample process reports and write your own process-driven project.

Writers of process texts are practicing what specialists call “expository writing” or “explanatory writing.” These texts focus on answering one of the following questions: “How is this done? How can I do this?”

Diverse Rhetorical Situations

Most prescriptive and descriptive processes are written to explain how something works. Most processes are written in chronological order and most rely extensively on visuals. To promote clarity, writers often number particular steps in a process. When the topic is learning a software program, writers use screenshots and call-outs and screen movies to walk a user through the tutorial.

Nonetheless, other purposes and organizational schemes are available. Writers may speculate about whether a process exists; they may argue a process exists with the intention of selling the reader something.

While the topics of process reports may be diverse, the rhetorical stance of most process reports tends to be more uniform than the rhetorical stance of other projects, as illustrated below.

Process Texts Purposes Audiences Voices Media

Descriptive Process Analysis

• Explain, speculate, or argue about “How is this done?”
• Students
• Researchers
• Curious people

• Objective
• Imperative
• Authoritative

• Essays
• Newspapers
• Magazines
• Web sites
• Video

Prescriptive Process Analysis

• Explain “How can I do this?”
• Technicians
• Users
• Decision makers

• Objective
• Imperative
• Authoritative

• Essays
• User manuals
• Policy manuals
• Tutorials
• Web sites
• Videos

Rhetorical Analysis of Online Readings

Analyze the Web sites annotated below. Consider the context, audience, purpose, and media invoked by the following readings. Also examine how ideas are developed in these texts. Are assertions grounded in personal experience, interviews with authorities, questionnaires, Internet and library research, or empirical research?

1. Instruction Processes: Recipes and Physical Processes

• How Pencils Are Made:Using an objective voice and extensive graphics, this piece is written to explain how pencils are made–not for future pencil makers but for interested readers.
• Yoga Postures Step-by-Step:  Santosha.com provides a searchable database of yoga postures. The description of each posture is supplemented by animations that show a figure doing the postures correctly. Presumably, readers will do more than read about the postures: they will try them!

2. Instruction Processes: Software Tutorials
Do you have a question about how to use a software tool, such as Microsoft Word, FrontPage, DreamWeaver, or HTML? As you can imagine, given the growth of the Internet and information technologies, tutorials and user manuals are exceedingly commonplace on the Internet. Below are links to several worthwhile sites.

• ToolsforWriters: Authored by writing students at the University of South Florida, this e-zine includes many tutorials on using software tools, including Microsoft Word, FrontPage, and Excel. Most of these tutorials have screen shots and call-outs, highlighting important steps.
• Catalyst: How To Documents. Authored by Center for Teaching, Learning and Technology at the University of Washington, “Catalyst is an integrated collection of resources, training, tools, templates, and support to help educators make effective use of technology in teaching.”

3. Instruction Processes: Personal Development
Do you ever have difficulties finding balance in your life–eating well, exercising regularly, balancing school with work? The Internet provides many “development” Web sites that are designed to help you change your life:

• Zen: The Seat of Enlightenment. The Zen Mountain Monastery provides a description of Zen meditation, including photographs and animated examples of breathing postures. From this site, readers can learn about The Zen Mountain Monastery, perhaps becoming sufficiently interested to enroll in some of the institute’s seminars.
• Ten Steps to Attract a Life Partner. Using a list form to organize her text, Katherin Scott, a personal development coach, outlines strategies for finding a life partner. From this site, readers can purchase coaching documents or inquire about workshops, so you could argue this text is written–in part–to sell the author’s expertise.
• Don’t Ask Me Where I’m Going. I’m Busy Driving. Steve Kaye writes this six-step guide to asserting control over your life for readers of Fluid Power Journal, a journal for engineers.

4. Instruction Processes: Academic Processes
Choosing majors, getting good grades, securing internships, researching topics–these topics are commonly addressed on university Web sites. You can go to your college’s home page and search for career resources, search the Internet, or consider the following examples to help you choose a career or do well in school:

• Undergraduate Advising at the University of Washington presents “How to Choose a Major and Investigate a Career.” Written for students, this site provides links to University of Washington resources as well as national resources.
• As a service to its students, Cornell University publishes ” The Seven Steps of the Research Process,”employing a hypertextual format.
• Using a hypertextual format, Duke University provides a guide similar to Cornell’s guide to the research process, also outlining seven steps: Guide to Library Research. In addition, the Duke guide provides a drop-down menu that addresses specific questions students pose when facing research assignments.
• Using internal hyperlinks, Athabasca University, a Canadian distance education university, provides The AU Library Guide to the Research Process.

5. Theoretical Processes: Psychological or Educational Development
Educators and psychologists have propounded many models of cognitive, moral, social, and intellectual development. Below are some links to some major theorists whose models of development have captured the imagination of others.

• Lawrence Kholberg’s model of ethical development is well presented on the Internet.
• The University of Illinois at Chicago presents a brief introduction to Kholberg and other developmental psychologists: Moral Development and Moral Education: An Overview.
• Kohlberg’s Moral Dilemmas (at Haverford College)
• William Perry’s Scheme of Intellectual and Ethical Development.
• Meet Your Students by Richard M. Felder.