A reminder: visual and other indexes

[Geoff Hart <ghart -at- videotron -dot- ca>]

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:
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- 

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:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat