Re: Task-based versus UI-based documentation

[yehoshua paul <ysp10182 -at- gmail -dot- com>]

I inherited a UI based context sensitive help, which I have been trying to
move to being a task based system.
With most of the major modules, clicking the help button opens a help topic
that provides an overview of the module, and a "What can you do on this
page?" subheading with links to individual topics, such as create a new
supplier account, or copy an existing supplier account. Users can also
search for these individual topics if all they are interested in is the
individual task.
The rest of the modules are UI based. The help on each module is a single
topic for each page or tab, providing an overview of the page or tab, and
then listing all the procedures that can be performed, and all the relevant
information relating to those procedures and the UI.
I think tables listing all the buttons, icons, fields, etc. interrupt the
flow so with the topics I have rewritten, users will often encounter steps,
such as: "Enter the search parameters," in which clicking on "search
parameters" opens a drop-down table listing all the available search
options. Users who are already familiar with these parameters, or view them
as transparent, can continue with the procedure, while users who are
unfamiliar with the parameters will open the table.

Yehoshua


On Thu, Aug 7, 2014 at 3:24 PM, Sweet, Gregory (HEALTH) <
gregory -dot- sweet -at- health -dot- ny -dot- gov> wrote:

> Task-based every time. If a customer asks for UI-based we might do a
> general lay-of-the-land type piece, but otherwise convince the customer why
> they really want task-based.
>
> We are dealing with a user community that is mandated by law to use our
> products. A lot of our tools are for use in extreme or emergency
> situations, and therefore used infrequently. Our users do not want to know
> what every button or interface element does. And they certainly don't want
> to read about them all and then figure out from that how to do what they
> need to do. They want exactly the steps they need to accomplish the task
> now.
>
> For any of our CBRNE/Severe Weather Event preparedness and response
> applications used as part of Incident Command Systems (ICS) we create Job
> Action Sheets (JAS). A JAS succinctly list the steps necessary to complete
> a specific job. There may be several tasks on one JAS. The idea is that you
> can take anyone, literally anyone, hand them the JAS and with little or no
> training, they can be proficient in the job. Since so much of our work is
> related to ICS most of our documentation ends up looking and feeling like a
> JAS, even if it happens to be called something else.
>
> Cheers!
> Greg
>
>
> > -----Original Message-----
> > From: techwr-l-bounces+gregory -dot- sweet=health -dot- ny -dot- gov -at- lists -dot- techwr-l -dot- com
> > [mailto:techwr-l-bounces+gregory -dot- sweet=health -dot- ny -dot- gov -at- lists -dot- techwr-l -dot- com]
> > On Behalf Of Cardimon, Craig
> > Sent: Thursday, August 07, 2014 8:00 AM
> > To: 'TechWR-L'
> > Subject: Task-based versus UI-based documentation
> >
> > On another forum I frequent, many of the projects discussed are required
> to
> > follow the UI. For example, each tab of the home page is a topic.
> >
> > I believe the members of this forum advocate task-based documentation,
> > but I thought I'd ask:
> >
> > What method do the TechWhirlers prefer: Task-based or UI-based
> > documentation?
> >
> > Personally, I do things in a UI-based manner because that is what my
> clients
> > want.
> >
> >
> >
> > Cordially,
> >
> > Craig Cardimon | Technical Writer
> > Marketing Systems Group
> >
> >
> > Information contained in this e-mail transmission is privileged and
> > confidential. If you are not the intended recipient of this email, do
> not read,
> > distribute or reproduce this transmission (including any attachments).
> If you
> > have received this e-mail in error, please immediately notify the sender
> by
> > telephone or email reply.
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > Read about how Georgia System Operation Corporation improved
> > teamwork, communication, and efficiency using Doc-To-Help |
> > http://bit.ly/1lRPd2l
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >
> > You are currently subscribed to TECHWR-L as gregory -dot- sweet -at- health -dot- ny -dot- gov -dot- 
> >
> > To unsubscribe send a blank email to
> > techwr-l-leave -at- lists -dot- techwr-l -dot- com
> >
> >
> > Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
> > http://www.techwhirl.com/email-discussion-groups/ for more resources
> > and info.
> >
> > Looking for articles on Technical Communications?  Head over to our
> online
> > magazine at http://techwhirl.com
> >
> > Looking for the archived Techwr-l email discussions?  Search our public
> email
> > archives @ http://techwr-l.com/archives
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Read about how Georgia System Operation Corporation improved teamwork,
> communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as ysp10182 -at- gmail -dot- com -dot- 
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> Looking for articles on Technical Communications?  Head over to our online
> magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions?  Search our public
> email archives @ http://techwr-l.com/archives
>

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Read about how Georgia System Operation Corporation improved teamwork, communication, and efficiency using Doc-To-Help | http://bit.ly/1lRPd2l

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

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-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications?  Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions?  Search our public email archives @ http://techwr-l.com/archives