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.
Is there such a thing as TMI (too much information)?
Subject:Is there such a thing as TMI (too much information)? From:"Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Tue, 19 Mar 2002 14:06:24 -0500
Jane Carnall wonders: <<Is there such a thing as giving people too much
John Carroll's work on minimalism (much of it done with van der Meij) has
revealed that information that doesn't support what readers need to know to
actually do tasks is often either useless or actively counterproductive.
While I get the impression that he sometimes overadvocates this approach in
defending himself against his critics, the overall approach seems sensible
and well-supported by research. It might help in your current situation too.
<<Well, if the people are being given more information than they can handle
(or is that bad design?) or if they are being given irrelevant information
that drowns out the relevant, yes...>>
That's certainly the Carroll definition of information you could exclude.
But the issue isn't necessarily whether there's too much information but
rather whether you delivered the information in the right place and at the
right time. The first type of problem arises if you include necessary
information in the wrong place; for example, "do this before proceeding"
information must appear before the procedure itself. The second arises when
you provide information the reader doesn't need now, but may need later;
that might occur if you place instructions on how to customize a series of
settings in the middle of instructions on how to use the standard settings.
Readers who don't need the customization info. have to filter it out, but
when they do need it, it had better be accessible.
<<What I plan to suggest, in addition: A series of focussed tipsheets,
listing the things they must not do.>>
That's certainly useful in an overview document, but more useful still if it
accompanies the actual steps that might lead them astray. Most readers will
encounter "thou shalt not" information while reading the procedure; far
fewer will read the overview. In short, place this kind of information with
the instructions that tell them how to do it right, not as separate tips.
(This also follows from Carroll's suggestion that error recovery information
should occur where the errors are most likely to occur--in mid-procedure.)
<<A rationale to accompany the questionnaire, giving reasons (and the
correct answer) to each question.>>
I have considerable sympathy for this approach, but Carroll points out that
it may be irrelevant for most users. The majority typically just want to do
the job, and could care less about why. Programming materials are a possible
exception because readers need to know their options and the consequences of
each choice. The trick is to integrate this seamlessly with the information
so that readers never know they're reading a justification; for example, you
could present a simple table that shows each option, it's preferred use, and
the consequences of using it outside that preferred use.
<<The tipsheets will tell them what we're going to tell them. The guide will
tell them what we're telling them. The rationale/questionnaire will tell
them that we've told them what we're telling them.>>
I'm less comfortable with this approach in print than I am in a
presentation, which is where the "tell them three times" approach
originated. In text, this kind of redundancy seems to work less well than
saying the same thing in _three different ways_ (e.g., here's how it works,
here's an example, and here's how it doesn't work). This is basic memory
psychology: providing the same information in different ways helps readers
integrate that information with existing knowledge and thus helps them
remember it better. By contrast, a presentation provides so many confounding
signals (background conversations, Powerpoint gymnastics) that repetition is
necessary in case the message got drowned out the first couple times.
<<Disadvantages that I've thought of already: three documents means three
different sets of updating to do.>>
As I've noted above, the updating becomes less tedious if the information is
tightly integrated with the main reference information. Then you only have
to update one section of one document when things change. Storing
information in several locations requires you to make notes of all the
places where that information lies; without doing this rigorously, the odds
are excellent that you'll fix a problem in one place and forget to fix it
<<The tipsheets are intended as icing on the cake - warning people off the
truly lethal (figuratively speaking) mistakes we've discovered they tend to
think are a good idea.>>
Tipsheets work well if they're the sort of things people pin to their
monitor or keyboard; remember the old keyboard templates that used to ship
with WordPerfect and that you attached over the top of the function keys?
The modern equivalents are cheat sheets or quick reference cards, which are
easily lost and (given the abundance of features) less likely to fit in this
space. (And why haven't we moved these things into online help, and make
them immediately accessible from the Help menu? I've done that in some of my
online help precisely because of how easy it is.)
But if the problems are truly "lethal", don't rely on easily lost and
seldom-read tipsheets; integrate the warnings with the main reference
material. Ideally, make it part of the API online help, so they can call up
the information directly in the same context in which they're using it. For
example, and API that lets programmers copy and paste code samples from the
online reference (so they don't have to retype an entire function) is a
great productivity aid, and providing the warning right where they're going
to see the code (before copying it) is most likely to get the warning read.
Combine this with a tutorial that emphasizes real examples and how to
examine them for potential problems and you've got a killer approach (just
stickin' with your "lethal" metaphor <g>).
Think of it another way: I've just gone back to debug a program I wrote
several months ago, and I've narrowed down the problem to something to do
with the Arglebargle module. Am I going to hunt up the tipsheet, or turn to
the page in the reference material or online help that describes this
module? If that section also contains a large, boldfaced heading labeled
"things that can go wrong with this function", you've saved me lots of time
<<The questionnaire is a given. Giving them an explanation for each question
means that we are assuming that they will want to do the right thing if they
know what it is.>>
What you're calling a questionnaire sounds more like a checklist, and the
name is important. Call it a "Checklist for writing a bulletproof procedure"
and you'll encourage them to consult it; call it a "questionnaire" and they
may never read it, on the assumption that it relates more to your needs than
<<The other option, as I see it, is to link each question to the
documentation, but this will also require last minute updating - they're
two separate documents, and AFAIK a self-updating hyperlink is not possible
unless we can guarantee they stay in the same directory - which we can't.>>
Sounds like an ideal situation for context-sensitive online help; that way,
everything sits in a single file intimately linked with the software, and so
long as the topic IDs don't change, the links-management challenge is much
lower. When the topics do change, all the information is in one place and
thus, you can manage the links from that one place instead of hunting all
--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
Hofstadter's Law--"The time and effort required to complete a project are
always more than you expect, even when you take into account Hofstadter's
PC Magazine gives RoboHelp Office 2002 five stars - a perfect score!
"The ultimate developer's tool for designing help systems. A product
no professional help designer should be without." Check out RoboHelp at http://www.ehelp.com/techwr
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.