A reminder: visual and other indexes

Subject: A reminder: visual and other indexes
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L Writing <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Sat, 09 May 2009 06:54:54 -0400

In another discussion group, someone reported a problem with a visual
indicator that suddenly appeared in her Word documents. Turns out it
was Word helpfully applying a paragraph border, probably because of
its "autoformat as you type" function. What's relevant to techwr-l was
her response, namely that Word's help wasn't helpful because she
didn't know what search terms to use. This provides a twofold reminder:

First, search tools are only useful if the user knows your top-secret
code words for a given concept. If not, they're SOL. So the first
reminder is that you should index your documents using the specific
words in the interface, the secret words you use to discuss them
(since those are the words your tech support people are likely to
learn by listening to you), and at least one synonym users are likely
to think up on their own.

The second is that most documentation provides no way to look up
things you can see on the screen. I've occasionally had problems with
Adobe documentation, for example, because they'll write something like
"to fram statically, use the framistat tool" without showing me what
that tool looks like or where it's hidden. Guys... if I knew how to
fram statically, I wouldn't be reading the documentation. Provide a
picture, please, or tell me which menu to look in!

But that also leads to an index-related suggestion: provide a visual
index too, particularly for things that don't have obvious names. The
last manual I read that provided such assistance (15 years ago?) was
the one for the AmiPro wordprocessor, which helpfully included a bunch
of visual references so you could learn what things were called _and
then_ use the word index to look them up. This may have been in the
days before "tooltips" (aka hovertext), or during the early days when
they weren't easy to create, but it does lead me to wonder how many
people have not learned that tooltips exist. I'd bet serious money
it's far more people than we think.

The problem arises because we technical writers are word geeks and
thus tend to forget that visual things are best looked up visually --
particularly when there's no way to hold the cursor over something and
wait for a popup to tell you what it is, as in the case of Word's
border formats. Even a single "weird things you may see on the screen
and what they mean" page would help.

Geoff Hart (www.geoff-hart.com)
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
Effective Onscreen Editing:


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.

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-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:


Previous by Author: Misc: Making outsourcing work for you (one for the Friday files)
Next by Author: A reminder: visual and other indexes (take II)
Previous by Thread: a (free) cross-software graphics book
Next by Thread: Re: A reminder: visual and other indexes

What this post helpful? Share it with friends and colleagues:

Sponsored Ads