Re: A reminder: visual and other indexes

Subject: Re: A reminder: visual and other indexes
From: Mike Starr <mike -at- writestarr -dot- com>
To: 'techwr-l List' <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Sat, 09 May 2009 10:50:21 -0500

This brings to mind my firm belief that complete documentation contains reference documentation despite current received wisdom that we should provide only procedural documentation.

Assuming I'm allowed to, I'll always provide chapters that describe the menus, toolbars, workspaces and dialog boxes. This also provides all of the content I need for single-sourcing context-sensitive help.

I maintain that the average user will seek the required information in their preferred format (print, PDF or online help) and if they don't find it there, they'll contact tech support (via phone, live chat or email... thus increasing support costs) rather than checking other documentation formats first.
Mike Starr WriteStarr Information Services
Technical Writer - Online Help Developer - Technical Illustrator
Graphic Designer - Desktop Publisher - MS Office Expert
(262) 694-1028 - mike -at- writestarr -dot- com -

Geoff Hart wrote:
> 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 (
> 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!

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

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 for more resources and info.

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

A reminder: visual and other indexes: From: Geoff Hart

Previous by Author: Re: Shazam! You're a marketing writer!
Next by Author: Re: A reminder: visual and other indexes
Previous by Thread: A reminder: visual and other indexes
Next by Thread: Re: A reminder: visual and other indexes

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

Sponsored Ads