TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Studies relating to documentation density and getting the user to read the manuals?
Subject:Studies relating to documentation density and getting the user to read the manuals? From:Geoff Hart <ghart -at- videotron -dot- ca> To:TECHWR-L Writing <techwr-l -at- lists -dot- techwr-l -dot- com>, The Documentation Doctor <documentationdoctor -at- googlemail -dot- com> Date:Tue, 17 Feb 2009 08:20:11 -0500
Martin wondered: <<A client has the common problem that users don't
read the installation manuals.>>
<Fe>The usual engineering solution is to make the installation
procedure so complex that it's literally impossible to succeed without
minute study of the documentation. This has become a "best practice"
in some fields (did anyone say "SAP"? <g>), but fortunately, it's also
an easy and robust solution to implement, and engineers are inherently
lazy. Best of all, it cuts down on those annoying post-installation
technical support calls: if they can't install it, they can't call to
ask how to use it.</Fe>*
<<Historically, the response has been to beef up the installation
manuals with big warning boxes highlighting the importance of
particular steps; so much so that the warnings duplicate about 30% of
the procedure. In addition, to make the manuals more friendly, each
and every dialogue box and message is documented and illustrated. Even
so, users still tend to skim, skip steps and get into a mess.>>
The problem that has arisen here is simple: the client has taught an
audience, and one that is already reluctant to read the documentation,
that there is no value to reading the documentation. You can't un-
teach that lesson. Thus, the actual solution is to _not_ try solving
things through documentation that you know most of the audience won't
read. The only correct solution is to design the installation software
such that it guides users gently through the task of performing the
installation.
Although this is not a traditional documentation role, it's one I've
occasionally taken on with considerable success: the same approach you
would use to design the documentation can be used to design the
sequence of actions in the installer. For example, if 30% of the
procedure is warnings, my experience suggests that many of the
warnings represent checkboxes, menus of choices, or sets of radio
buttons that users can select right at the start of the installation,
and then go away to have a cup of coffee. Others represent precautions
such as backing up the old installation that should be automatic
rather than left to the user's discretion. Why warn them to make a
backup you know they won't make when you can create that fallback
solution for them?
In fact, many of the best installers simply offer two options: default
(install what we know you'll need to create a working installation)
and custom (select all details that are user-customizable right at the
start, then go away and let the installer do its work). An interesting
way to sell this solution is to point out that it can potentially
eliminate the entire installation manual. If they know the cost of
writing and printing that manual, they know how much money they
instantly save by eliminating it, and that money may even completely
pay for your services.
<<My contention is that users are more likely to read documentation
that is terse and does not contain redundant information, and that a
single "Follow the steps or suffer the consequences" warning will
suffice.>>
It's true that dense procedures liberally bestrewn with warnings are
intimidating, and scare people away. But the "single warning" approach
may fail for several reasons: First, there may be legal requirements
for warnings at all steps that risk harm or loss of information.
Second, warnings must be specific, not general; a simple "pay
attention, doofus" warning doesn't provide enough details of what to
beware. Third, such warnings are long forgotten by the time readers
reach the middle of a long procedure.
Thus: If you're going to try to solve the problem through
documentation, you must do it by building the warnings into the steps
so that separate warnings are unnecessary. For example, instead of the
warning sidebar "Unplug the widget before opening its case", make
"Unplug the widget" step 1 of the procedure, and reiterate this in
step 7 as backup: "Before opening the case, ensure that the green
light is off; if not, unpug the widget."
<<So, what I'd be grateful for would be links to any studies that I
could cite in order to support (or invalidate!) my position.>>
Karen Schriver's book "Dynamics in Document Design" provides a lengthy
discussion of how people use documentation, accompanied by many
examples of case studies in design. It's not to everyone's taste, but
I love the book (it's a goldmine of useful information), and you can
find copies in most good libraries so you can check it out yourself
before deciding to buy.
--------------------------------------------------------
Geoff Hart (www.geoff-hart.com)
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
--------------------------------------------------------
***Now available*** _Effective onscreen editing_
(http://www.geoff-hart.com/books/eoe/onscreen-book.htm)
ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing
solution. Author in Doc-To-Help's XML-based editor, Microsoft Word or
HTML and publish to the Web, Help systems or printed manuals. http://www.doctohelp.com
Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
