A reminder: visual and other indexes (take II)

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

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  
time.>>

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  
keywords.

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