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

Subject: RE: Do we help the user complete the immediate task or ultimate goal?
From: "Leonard C. Porrello" <Leonard -dot- Porrello -at- SoleraTec -dot- com>
To: "techwr-l List" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 6 Mar 2008 11:22:42 -0800

I wasn't clear enough when I said, "Whichever one chooses, it should
remain consistent throughout the docs". What I meant was, "Whichever
voice one chooses to write step-by-step directions, it should remain
consistent throughout the docs." In other words, it wouldn't do to
flip-flop between "immediate task" voiced steps and "ultimate goal"
voiced steps. For example, a step-by-step procedure like the following
would be ghastly:

1. Enter the approval date.
2. Enter a date in the Acceptance Date field.

Perhaps this isn't the best example, but you can see how #1 orients the
user toward the telos of the task while #2 gives the user a specific
point of reference in the GUI while leaving the telos implied. Of
course, one could make the telos of #2 more explicit by saying, "Enter
the acceptance date in the Acceptance Date field", but that, obviously,
is untoward.

And of course, by saying that voice should be consistent "throughout the
docs", I do not intend a slavish consistency. Obviously, it would not be
incorrect to follow #1 with "Click OK" rather than with an "ultimate
goal" voiced step (which would sound ridiculous).

The question I had in mind comes into play after the pedestrian albeit
eloquently stated considerations Geoff has spoken about are taken into
consideration.

Leonard C. Porrello
SoleraTec LLC
www.soleratec.com



-----Original Message-----
From: Geoff Hart [mailto:ghart -at- videotron -dot- ca]
Sent: Thursday, March 06, 2008 10:45 AM
To: techwr-l List; Leonard C. Porrello
Subject: Do we help the user complete the immediate task or ultimate
goal?

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.


References:
Use of 'populate': From: Michelle Vina-Baltsas
RE: Use of 'populate': From: Combs, Richard
RE: Use of 'populate': From: Gilbert, Brian
Do we help the user complete the immediate task or ultimate goal?; was, "RE: Use of 'populate'": From: Leonard C. Porrello
Do we help the user complete the immediate task or ultimate goal?: From: Geoff Hart

Previous by Author: Do we help the user complete the immediate task or ultimate goal?; was, "RE: Use of 'populate'"
Next by Author: RE: Thank You from new tech writer
Previous by Thread: Do we help the user complete the immediate task or ultimate goal?
Next by Thread: RE: Use of 'populate'


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


Sponsored Ads