Table Of ContentWriting and Designing
Manuals and Warnings
Writing and Designing
Manuals and Warnings
Fifth Edition
Patricia A. Robinson
CRC Press
Taylor & Francis Group
6000 Broken Sound Parkway NW, Suite 300
Boca Raton, FL 33487–2742
© 2020 by Taylor & Francis Group, LLC
CRC Press is an imprint of Taylor & Francis Group, an Informa business
No claim to original U.S. Government works
Printed on acid-free paper
International Standard Book Number-13 978-0-367-11109-0 (Hardback)
This book contains information obtained from authentic and highly regarded sources. Reasonable
efforts have been made to publish reliable data and information, but the author and publisher
cannot assume responsibility for the validity of all materials or the consequences of their use. The
authors and publishers have attempted to trace the copyright holders of all material reproduced in
this publication and apologize to copyright holders if permission to publish in this form has not
been obtained. If any copyright material has not been acknowledged, please write and let us know
so we may rectify in any future reprint.
Except as permitted under U.S. Copyright Law, no part of this book may be reprinted, reproduced,
transmitted, or utilized in any form by any electronic, mechanical, or other means, now known or
hereafter invented, including photocopying, microfilming, and recording, or in any information
storage or retrieval system, without written permission from the publishers.
For permission to photocopy or use material electronically from this work, please access www.
copyright.com (www.copyright.com/) or contact the Copyright Clearance Center, Inc. (CCC), 222
Rosewood Drive, Danvers, MA 01923, 978-750-8400. CCC is a not-for-profit organization that
provides licenses and registration for a variety of users. For organizations that have been granted a
photocopy license by the CCC, a separate system of payment has been arranged.
Trademark Notice: Product or corporate names may be trademarks or registered trademarks, and
are used only for identification and explanation without intent to infringe.
Library of Congress Cataloging‑in‑Publication Data
Names: Robinson, Patricia A., 1948– author.
Title: Writing and designing manuals and warnings / authored by
Patricia A. Robinson.
Description: Fifth edition. | Boca Raton : CRC Press, 2020. | Includes
bibliographical references and index.
Identifiers: LCCN 2019036123 (print) | LCCN 2019036124 (ebook) |
ISBN 9780367111090 (hardback) | ISBN 9780429025372 (ebook)
Subjects: LCSH: Technical writing.
Classification: LCC T11 .R635 2020 (print) | LCC T11 (ebook) | DDC
808.06/66—dc23
LC record available at https://lccn.loc.gov/2019036123
LC ebook record available at https://lccn.loc.gov/2019036124
Visit the Taylor & Francis Web site at
www.taylorandfrancis.com
and the CRC Press Web site at
www.crcpress.com
Dedication
This book is dedicated to all my
students, in classrooms and seminars,
in formal and informal settings. I’ve
learned more from you than I can say.
Contents
Preface to the Fifth Edition ������������������������������������������������������������������������������������xvii
Acknowledgments ���������������������������������������������������������������������������������������������������xix
Author ���������������������������������������������������������������������������������������������������������������������xxi
PART I Product Safety in the 21st Century
Chapter 1 The Changing Landscape ���������������������������������������������������������������������3
Overview ����������������������������������������������������������������������������������������������3
Why Do We Still Need Manuals? ��������������������������������������������������������3
The Customer �����������������������������������������������������������������������������4
First-Time Operation ������������������������������������������������������������������4
Ongoing Reference ���������������������������������������������������������������������5
Product Safety Resource ������������������������������������������������������������5
The Company ���������������������������������������������������������������������������������������6
Required Documentation �����������������������������������������������������������6
Product Development Resource �������������������������������������������������7
Marketing and Public Relations Document �������������������������������8
What’s Changed? ����������������������������������������������������������������������������������9
Higher Expectations �������������������������������������������������������������������9
Safer Products ����������������������������������������������������������������������������9
Better Instructions and Warnings ��������������������������������������������10
Information on Demand �����������������������������������������������������������11
Definition of Product ��������������������������������������������������������������������������11
“Hey, Alexa!” Technology Permeates Everything �����������������������������12
Alternatives to Reality �������������������������������������������������������������12
The Internet of Things �������������������������������������������������������������12
The Global Village �����������������������������������������������������������������������������13
Expanded User Groups ������������������������������������������������������������14
Bridging Communication Challenges ��������������������������������������15
Proliferating Standards and Laws ������������������������������������������������������18
European Union Requirements ������������������������������������������������18
International Standards ������������������������������������������������������������20
Law and Regulation �����������������������������������������������������������������21
Summary ��������������������������������������������������������������������������������������������22
Notes ���������������������������������������������������������������������������������������������������23
Chapter 2 Know Your User and Your Product’s Hazards �����������������������������������25
Overview ��������������������������������������������������������������������������������������������25
Keep the User Safe! ����������������������������������������������������������������������������25
vii
viii Contents
Is My Product Reasonably Safe?����������������������������������������������25
Risk vs� Utility ���������������������������������������������������������������26
Available Alternatives ���������������������������������������������������26
Consumer Expectations �������������������������������������������������26
What Is “Reasonably Safe” Depends on Who’s
Using the Product ����������������������������������������������������������������26
Who Are the Users (And Will They Read What I Write?) ����������������27
Why Do I Need to Find Out about My Audience? ������������������28
Sources of User Information ����������������������������������������������������29
Sales Records �����������������������������������������������������������������29
Sales and Service Personnel ������������������������������������������30
Marketing Reports ���������������������������������������������������������31
Product Development Reports ���������������������������������������31
Trade Journals ���������������������������������������������������������������31
Other Sources ����������������������������������������������������������������32
Who Are These People? �����������������������������������������������������������32
Age ���������������������������������������������������������������������������������32
Gender ���������������������������������������������������������������������������34
Culture and Geography �������������������������������������������������35
Literacy and Language ��������������������������������������������������37
Are Your Users Sophisticated? ������������������������������������������������38
What Are the Hazards and What Should We Do about Them? ���������39
What Is a Hazard Analysis? �����������������������������������������������������39
Why Do a Hazard Analysis—And When Should We
Do It? �����������������������������������������������������������������������������������40
New Product Development ��������������������������������������������40
Existing Products �����������������������������������������������������������41
Model Changes ��������������������������������������������������������������41
Throughout the Life Cycle of the Product ���������������������41
How to Conduct a Hazard Analysis �����������������������������������������42
Make It Systematic and Comprehensive �����������������������42
What Method Is Best? ���������������������������������������������������43
Are There Regulations and Standards That
Apply to Hazard Analysis? ���������������������������������������45
Shouldn’t the Engineers Be Doing All This? ���������������������������46
Why You Need a Cross-Disciplinary Team ������������������46
“Shop-Blindness” Can Be Costly ����������������������������������46
The “Person on the Street” May Be Your New
Best Friend ����������������������������������������������������������������47
We Found a Hazard� What Now? ��������������������������������������������47
Assess Severity and Likelihood ������������������������������������47
Apply the Hazard Control Hierarchy ����������������������������49
Apply a Rational, Standardized Mitigation
Process ����������������������������������������������������������������������51
Document, Document, Document! ��������������������������������52
Summary ��������������������������������������������������������������������������������������������53
Contents ix
Checklist: Users and Hazards ������������������������������������������������������������53
Notes ���������������������������������������������������������������������������������������������������54
PART II The Making of a Manual
(Or More Than One!)
Chapter 3 Designing a User-Friendly Manual ����������������������������������������������������59
Overview ��������������������������������������������������������������������������������������������59
What Do Users Want? ������������������������������������������������������������������������59
When All Else Fails � � � �����������������������������������������������������������59
They’re Boring ���������������������������������������������������������������59
They’re Hard to Read ����������������������������������������������������60
They’re Confusing ���������������������������������������������������������60
They Don’t Answer My Questions ��������������������������������61
The Unwritten Goal of a Successful Manual ���������������������������61
Creeping Featurism �������������������������������������������������������62
Cognitive Friction ����������������������������������������������������������62
Productivity Paradox �����������������������������������������������������62
How Do People Use Manuals? �����������������������������������������������������������62
How Do I � � � ? �������������������������������������������������������������������������63
What’s This Thing For? �����������������������������������������������������������63
All I Want to Know Is � � � ��������������������������������������������������������64
I Don’t Have All Day ���������������������������������������������������������������65
My Inbox Runneth Over ����������������������������������������������������������65
You Can’t Put a Tractor on a Desk �������������������������������������������66
Manual? What Manual? Keeping Product and Manual
Together �������������������������������������������������������������������������������67
Choosing Content �������������������������������������������������������������������������������68
User Questions as Manual Organizers�������������������������������������68
You Can Say That Again: Useful Redundancy ������������������������69
How to Use the Product Is Not the Same as How
It Works �������������������������������������������������������������������������������70
Focus on the Need-to-Know ����������������������������������������������������70
Organizing Content: Cookbooks, Not Novels ������������������������������������71
I Want to Make an Apple Pie—Why Must I Read
about Beef Stew? �����������������������������������������������������������������71
Mix and Match: Using Modular Organization ������������������������73
Designing for the Two-Page Spread ����������������������������������������75
Make the Language Accessible ����������������������������������������������������������76
Language Level and Readability Indices ���������������������������������76
Who Are Your Users? Are You Sure?��������������������������������������76
Jargon, Slang, and Technical Language �����������������������������������77
The Importance of Consistency �����������������������������������������������78