S1000D-compliant illustrations - ISTC

44 Indexing
The finishing touch
Bill Johncocks launches his regular indexing page by
explaining how a good index makes a manual fully usable.
Manning an IT helpdesk can be pretty
soul-destroying and a really clueless
caller can provoke the staff to intone
‘RTFM’, an acronym where three of the
letters stand for Read The Manual. It
seems nobody can win in a helpdesk
interaction, because every contact grows
out of an initial failure. Certainly users
who psyche themselves up to make a
long and humiliating call must first have
felt at least equal frustration. They know
the solution is at their fingertips; they just
can’t find it using the index, and that’s
because user manuals have some of the
most unusable indexes in the world.
Why is this? After all, most manuals
are painstakingly compiled by
intelligent, dedicated professional
communicators — people just like you
and people, presumably, not too unlike
professional indexers. So why are so
many of their indexes dire? I think
the answer is simple: most technical
communicators still omit the first,
crucial stage of constructing a usable
index, which is to imagine yourself in
the reader’s shoes.
Thinking like your readers
A book index may serve two readerships:
those who have read the book and are
looking for something they recall seeing,
and those who haven’t, but want to
find a relevant section (and, where that
section addresses an urgent problem,
as in a book on dealing with household
emergencies, the index must be
efficient). We know nobody wants to read
an entire manual — they’d even rather
call a helpdesk — so the second role
must be important for manuals too, but
their indexes often address just the first,
assuming a familiarity with specialised
vocabulary that the first-time reader
can’t possibly have attained. Precise
and consistent wording is a virtue in
section headings and captions but transferring
these terms without thought can
produce a completely unusable index.
Most manuals start by naming components,
then go on to describe how things
work. Often though, readers won’t know
those names or want that explanation:
their approach is use-centred, arising
from a real-world need, and they expect
to be guided quickly to its solution. They
Communicator Spring 2006
might look for ‘Punctures’ not for ‘Wheel
changing’, say, or for ‘Starting’ not for
‘Ignition subsystem’.
Full-time indexers try to approach
documents from the likely reader’s
viewpoint, whereas even authors with
good indexing skills can grow so used
to their chosen terminology that they
risk being trapped within it. Full-time
technical writers, retained to document
a specific project, presumably start
out with a detached view too, but may
quickly find themselves becoming
‘institutionalised’.
Special problems with consumer guides
Paradoxically, it’s not the most
technical material that causes the worst
problems: it’s in indexes to consumer
product guides where the disparity
in knowledge and vocabulary yawns
widest. The author of a textbook on
semiconductor theory will write at a
level suiting its intended readership: the
author-indexer of a short user guide for
a digital camera actually has a harder
job and one needing more imagination.
After living with the product and
becoming steeped in its jargon, he or
she may already speak a quite different
language from its purchasers.
Worse, manual authors sometimes have
to aim at a moving target. Because good
technical writing educates and informs, a
reader who starts out knowing no more
than that the product is recommended
by the guy down at the pub or by Which?
magazine should, after a few pages,
be familiar with the control layout,
the meaning of any error messages or
warning lights and the names of key
components and operations. This calls
for real subtlety in separating low-level
information from the more advanced, and
indexing both appropriately, although a
well-designed manual’s structure should
reflect this progressive acquisition of
expertise and so provide clues.
Usability testing
A good book index might just swing
purchasing choices in bookshops but
manuals aren’t often available before
purchase so, where user documentation
is concerned, customers have to buy a pig
in a poke. But get it right and (assuming
the product also does its job) customer
satisfaction and brand loyalty should
be guaranteed. Really good technical
indexing is a rare skill but an author
who recognises indexing as a separate
problem has already taken the key step.
Might drafting an outline of each
new project in users’ language,
before you immerse yourself in the
specialised vocabulary needed for its
documentation, be time well spent? And,
on completion, don’t just get your work
approved by the in-house development
and marketing teams: why not test it on
colleagues uninvolved with the project
or (if commercial confidentiality allows)
on friends or relatives with similar
backgrounds to the intended users? If
your in-laws find your instructions for
connecting up a new DVD player hard
to follow, they probably won’t be alone.
Nor will they if they look in the index
for terms you didn’t expect. Those they
do look for might be good candidates
for index entries.
Getting help
Whether you index technical publications
yourself or find a specialist through the
Society of Indexers, do take it seriously.
Most of us only read enough of a manual
for our immediate needs, then return
to it when we meet new challenges, so
nothing you write should be read more
than once. If it was understood the first
time, it has done its job but, if your
readers have to scan pages again, looking
for things they can’t find in the index,
you’ve failed as a communicator no
matter how clear your text and diagrams.
And, while a rare skill, indexing needn’t
be a big chore: training is available through
the Society, common sense is fully
applicable and future articles on this page
should help you produce indexes that
take readers straight to solutions, without
needing to make any telephone calls. C
Bill Johncocks is a freelance Accredited
Indexer living on the Isle of Skye, who
specialises in embedded indexing of
technical documents.
E: bill.johncocks@btconnect.com
W: www.technicalindexing.com
Society of Indexers: www.indexers.org