Writing and Designing Manuals and Warnings, Fifth Edition

Patricia A. Robinson

• Éditeur: CRC Press
• Année: 2019
• ISBN:
  9780429655579
• Édition: 5
• Sujet: Technik & Maschinenbau
• Sous-sujet: Gesundheit & Sicherheit in der Industrie

Technology is changing the way we do business, the way we communicate with each other, and the way we learn. This new edition is intended to help technical writers, graphic artists, engineers, and others who are charged with producing product documentation in the rapidly changing technological world. While preserving the basic guidelines for developing manuals and warnings presented in the previous edition, this new edition offers new material as well, including a much-expanded section on hazard analysis.

Features

• 
  
  

• Provides more explicit guidance on conducting a hazard analysis, including methods and documentation

• 
  
  

• Offers in-depth discussion of digital platforms, including video, animations, and even virtual reality, to provide users with operating instructions and safety information

• 
  
  

• Incorporates current research into effective cross-cultural communication—essential in today's global economy

• 
  
  

• Explains new US and international standards for warning labels and product instructions

• 
  
  

• Presents expanded material on user analysis, including addressing generational differences in experience and preferred learning styles

Writing and Designing Manuals and Warnings, Fifth Edition explores how emerging technologies are changing the world of product documentation from videos to virtual reality and all points in between.

Part I
Product Safety in the 21st Century

1
The Changing Landscape

OVERVIEW

The first edition of this book was published in 1984. To put that in context, the first personal computer (desktop) had been released only about ten years earlier. Illustrations for manuals were drawn by humans wielding technical pens. Thirty-five years later, we live in a much different world. Yet, most tangible products (as opposed to software) are still accompanied by a manual—of some kind. Today that “manual” may be a YouTube video or a QR code on the packaging that takes you to a website with animations and .pdfs of instruction sheets. Sometimes the instructions for using a product are built right into the product, especially if it has a screen as an interface. But quite often you still get a paper manual.

Still, much has changed—and the pace of change is only accelerating. Customers and companies have much higher expectations for products and manuals than they did in 1984. The definition of “product” has expanded to include not just the instructions and warnings that accompany it, but sales and marketing materials as well. Technology has altered the ways in which we interact with products and is even allowing products to interact with each other without human input. And international commerce and multinational companies are now the norm rather than the exception, bringing along proliferating international standards and regulations. The previous edition of this book devoted a single chapter to writing manuals for the global marketplace. This edition assumes your manuals will be used worldwide. And it assumes that your product will still be accompanied by a manual—in some form.

WHY DO WE STILL NEED MANUALS?

If you’re reading this book, chances are you are engaged in some way with manuals. You may be a technical writer laboring to produce manuals. You may be an attorney involved in a products liability lawsuit. You may be in charge of product safety at your company. You may be a marketing director who recognizes that the manual is perceived as part of the product “package.” This book focuses on writing and designing standard product manuals composed of words (most of the time) and graphics, whether the product user sees them in paper or digital form.

Manuals, in whatever form they appear, are still around because they fulfill a variety of necessary functions. Some of these are obvious, but others, while less apparent, are just as important—maybe more so. One way to look at the functions of a manual is to consider how a good manual benefits both the customer and the company—or how a bad manual hurts them.

THE CUSTOMER

The obvious function of a manual is to educate the customer to use and maintain the product properly. Manufacturers have a legal duty to tell their customers how to safely use and care for their products (more about this duty in Chapter 9). It doesn’t matter whether the product is a hundred-dollar string-trimmer purchased by a homeowner or a million-dollar veneer press purchased by a wood products company. The duty is the same—though the products and users are different. As we shall see, the legal duty is to provide information, but the underlying need is to facilitate proper and safe behavior. Accomplishing these goals requires close attention both to what you say and how you say it. Essential information packaged in incomprehensible prose does little good—but the most readable manual in existence won’t help if critical information is missing.

Regardless of the vast differences among them, all customers expect a manual to serve three basic purposes:

• Explain how to operate (or maintain) the product the first time they use it.
• Provide reference information they can use throughout the product’s life.
• Serve as a safety resource.

These three functions are quite different, and require different organizational and writing strategies to fulfill them.

FIRST-TIME OPERATION

The user operating the product for the first time naturally needs more information and guidance than an experienced user of the product or similar product. If it’s your very first time using a new product, you need to know everything about what to do—and what not to do—to operate the product properly. Particularly if the product is itself brand new (that is, innovative), the writer must be sure to provide enough information to the first-time user. That’s not as easy as it sounds. In fact, one of the most difficult tasks of the technical writer is to include all the information that the first-time user needs.

Why is it so hard? Simple: because as a technical writer working for the manufacturer, you’ve been living and breathing the product for a matter of weeks, if not months. Through countless discussions with engineers and other product developers, you know the product like the back of your hand. If you have spent eight hours a day for several weeks immersed in developing sufficient expertise to write about the product, it’s difficult to remember what it was like the first time you encountered it. You have become so familiar with it that you’re apt to assume knowledge on the part of the user that he or she just doesn’t have. If you misjudge how much your reader knows, the result is a confused and frustrated user.

What does the first-time user need? In general, first-time users need these categories of information:

• Intended uses and limitations of the product.
• Names and locations of parts and controls.
• Step-by-step procedures for installing, starting, operating, shutting down, maintaining, and (sometimes) storing the product.
• Safety information and warnings about hazards associated with using the product.
• Troubleshooting information and (sometimes) repair procedures.
• Contact information for the manufacturer.

Unless you have learned to look at your product as a first-time user, it’s easy to forget some of them—especially the first two categories. When your own company manufactures the product, you tend to take for granted what it’s used for and what the specialized terminology associated with it means. A first-time user may have a general idea of the product’s purpose, but not know all the possible uses and certainly may not know its limitations. And unfamiliar terms can put up a sizeable barrier for the first-time user.

ONGOING REFERENCE

A second customer-related function of a manual is for use as an ongoing reference. Many manual writers openly acknowledge this purpose by advising the reader to “read and save these instructions.” For consumer products, this admonition often results in a kitchen drawer crammed full of an assortment of manuals and instruction sheets. For industrial products, the equivalent is shelf upon shelf of three-ring binders lined up in the purchasing agent’s office. Either way, the user has a source to look up specific information that is not needed on a daily basis: How do you change the filter for the refrigerator water dispenser? What’s the procedure for lubricating the bearings on the outfeed conveyor? What’s the tolerance for blade wear on the slitter machine? The answers to all these questions (and many more) make up the reference function of a manual.

Reference material is every bit as vital to users as first-time operation instructions, but it is not nearly as easy to organize and write. Writers must not only understand and be able to explain an astonishing variety of processes and procedures, but they must also anticipate the user’s need for information and organize the information for easy retrieval. If the information is too difficult to locate, users are apt to become frustrated and give up looking for it. They will then try to get along without the needed information—either by trying to figure out what to do on their own or by contacting the manufacturer for technical assistance. Either option can be costly.

PRODUCT SAFETY RESOURCE

Another function of a manual for customers is to provide comprehensive information on using a product safely. As we shall see, on-product warning labels are usually reserved for the most severe hazards, and are limited in the amount of information they can convey before they lose their effectiveness. The manual can expand on label information as well as give additional safety-related information about the product. For example, the label on the product may warn the user to “keep hands away from moving parts.” While that message is important, it leaves some questions unanswered: How far away should I keep my hands? How close is too close? Where should my hands be when I’m operating the product? How do I clear a jam in those moving parts? How do I lubricate them? The manual can answer all those questions in detail.

The manual can do much more than simply expand on product labels. Not every hazard associated with a product needs to have a corresponding warning label. In fact, the more labels plastered all over the product, the less effect each one has. The effect is similar to the way that putting “New! Improved!” on the dish detergent label will catch the consumer’s eye—unless every other brand has the very same words on their label. In that case, no one stands out more than the others. For that reason, on-product warning labels should be limited to the most serious hazards. But what about the other hazards? How do users learn about those?

Manuals offer an opportunity to expand on safety information. In some cases, all that is needed is a fuller explanation of information on the label. But often the user—especially the first-time user—needs much more. In some circumstances, the manufacturer may provide a separate safety manual that explains safe working procedures for a class of products—for example, printing presses or air compressors. Other times, the manufacturer may include a safety section at the front of the manual that includes general safety information as well as warnings specific to the product. In all cases, the manual is expected to include at a minimum, warnings relating to the product it covers.

THE COMPANY

A well-designed manual (or manuals) clearly benefits the customer by providing needed information in a convenient and accessible package, but manuals also benefit companies that manufacture products. One of the changes in the field over the last 35 years is the recognition that product documentation does not merely add cost to the manufacture of products—it actually adds value. The value-added aspect of a good manual becomes increasingly clear as companies move more and more into global marketplaces. Good product documentation is a requirement for European Union compliance and for ISO certification. For ISO 9000 quality assurance, for example, all but two of the 20 major system elements explicitly mention documentation as vital, and the other two elements imply it. Whether in the United States or abroad, good documentation provides tangible benefits for the company as well as the customer.

REQUIRED DOCUMENTATION

While providing operational and reference information that users need, manuals also provide historical information companies need. Products do not remain static; manufacturers continuously seek to improve them. Whether in response to customer feedback or marketplace competition, the engineers are always tweaking this and altering that. Depending on the product, this constant change process can be very rapid or relatively slow. Either way, the product itself is always a moving target.

Ongoing evolution of product design is the source of one of technical writers’ biggest frustrations: just when you think you have the manual draft complete, the engineers change something and the rewriting begins. It’s also a source of frustration for users, because rarely will a company wait for the documentation to catch up before shipping the product out the door. As a consequence, the user is often looking at a manual that is a little out of date. For a first-time user who is not already familiar with the product, the difference between the product in hand and the description of the product in the manual can create a considerable obstacle to understanding.

Even so, manuals become the historical record of a product’s evolution. So what? Other than to satisfy an academic interest, why would anyone need such a thing? The author of a book on writ...