A reminder: visual and other indexes (take II)

Subject: A reminder: visual and other indexes (take II)
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L Writing <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 11 May 2009 10:41:36 -0400

Robert Lauriston noted: <<Yeah, it's very annoying when docs don't
tell you how to navigate to the command / dialog being discussed, but
screenshots of menus just clutter up the doc and waste the writer's

Indeed, the key point is whether the visual is necessary to help
readers find their way, or simply eye candy intended to break up a
page of text. My point was that the visuals must support the user, not
just document the interface; my specific example was a purely visual
problem that could not be found easily (or at all) by guessing at the

In my own book, I largely avoided using menu screenshots, and instead
used phrases such as "open the X menu and select Y", since that is
space-efficient and helps everyone, no matter their level of
expertise, find the feature they're seeking.

Craig Haiss noted: <<Perhaps the clutter of UI information can be
reduced by grouping all such content into a single chapter of the
documentation. If the chapter is clearly introduced in the opening
paragraph and table of contents, users can simply skip it if they
aren't interested.>>

Precisely my point: this is why I proposed the notion of a visual
index, which places the definitions of visual information exactly
where you'd expect to find it: alongside the textual index. If memory
serves, the AmiPro index had the visual definitions and associated
page references running in a band across the bottom of the text index,
so that it wasn't necessary to tell the users the index existed: they
found it as soon as they turned to the text index.

But where possible, we should also avoid "taking users out of their
task", which is to figure out how to use a feature. The problem with
placing visual information in a separate chapter or index is that we
make users stop what they're doing (following the steps of a
procedure) and go searching elsewhere for the visual details. That's
not necessary nor is it kind. This is why I stated "give me a picture"
for things like icons; it's easy to do. If I see the image right
beside the step I'm trying to figure out, I don't have to go look it
up somewhere.

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:


Re: A reminder: visual and other indexes: From: Craig Haiss

Previous by Author: A reminder: visual and other indexes
Next by Author: Question about price quotes and time estimates?
Previous by Thread: Re: A reminder: visual and other indexes
Next by Thread: Re: A reminder: visual and other indexes (take II)

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

Sponsored Ads