Do we help the user complete the immediate task or ultimate goal?

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

Leonard Porrello wonders: <<Brian's illustration raises the important  
distinction of whether one is writing with the intent of helping the  
user to complete the immediate task or the ultimate goal. "Enter the  
date in the Approval Date field" puts the user in mind of the  
immediate task, namely, filling in GUI or command line fields. "Enter  
the approval date" puts the user in mind of the ultimate goal,  
namely, getting the application to do something. Whichever one  
chooses, it should remain consistent throughout the docs (of course).  
I wonder which (if either) is better and why.>>

Which is better? Neither. We must provide both an overall orientation  
that provides sufficient context for the low-level tasks, and we must  
provide details for most or all of those low-level tasks. One of the  
biggest failings of most of the help systems that I use is that the  
steps are well explained, but there's no context that tells me why I  
should be doing these steps and whether other steps would be more  
relevant to my goals. There's rarely any explanation of how the  
current steps fit within the larger context of a multi-stage task or  
what my alternatives are.

In my opinion, books like the "For Dummies" series are purchased by  
the truckload because they provide that missing context. A close look  
at many introductory books such as the "For Dummies" series shows  
that most of their content (specifically, the detailed steps to  
accomplish a task) rarely go beyond what is already available in the  
online help. But these books provide context for the steps, and show  
how everything fits together, and that makes them more valuable.

Superficial consistency (doing the same thing everywhere) is largely  
irrelevant; consistently meeting the user's needs is the truly  
important form of consistency. Here's a simple, if somewhat extreme,  
example that illustrates the point. Superficial consistency would  
suggest that we provide the same level of detail for the step "Enter  
your name" as we do for the step "Choose one of the five available  
options". Needs-related consistency is more important. Clearly, we  
don't have to tell users _anything_ about entering their name unless  
the interface is so poorly designed that an explanation of formatting  
and other details is necessary. In contrast, we may need to provide  
an explanation of when each of the five available options is the best  
choice -- and when the choice doesn't really matter. Providing this  
extra detail appears inconsistent if we don't provide comparable  
detail for "enter your name", but it's consistent with presenting all  
the information the reader needs to know -- and not wasting their  
time with information they already know.


----------------------------------------------------
-- Geoff Hart
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
www.geoff-hart.com
--------------------------------------------------
***Now available***  _Effective onscreen editing_
(http://www.geoff-hart.com/home/onscreen-book.htm)


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or 
printed documentation. Features include support for Windows Vista & 2007 
Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! 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.