Re: Why I Hate GUI-Centric Docs (Long)

["Mike Starr" <mikestarr-techwr-l -at- writestarr -dot- com>]

The problem as I see it is that whoever created the documentation you 
struggled with just plain left out the task-based portion of the 
documentation. I'm a firm believer in doing both... task-based documentation 
to help the user accomplish the most common tasks and reference-based 
documentation (which is what you call GUI-centric documentation) to help the 
user understand the nit-picky little details that never get covered in 
task-based documentation. I suggest that any documentation set that provides 
one without the other is poor documentation.

Mike
--
Mike Starr                            WriteStarr Information Services
Technical Writer   -   Online Help Developer   -    Website developer
Graphic Designer    -    Desktop Publisher   -       MS Office Expert
Phone: (262) 694-1028 - Tollfree: (877) 892-1028 - Fax:(262) 697-6334
Email: mike -at- writestarr -dot- com      -      Web: http://www.writestarr.com

----- Original Message -----
From: "Janice Gelb" <Janice -dot- Gelb -at- Sun -dot- COM>
To: <techwr-l -at- lists -dot- techwr-l -dot- com>
Sent: Wednesday, July 25, 2007 5:59 PM
Subject: Why I Hate GUI-Centric Docs (Long)

> Every once in a while, a discussion about how/when
> to document the buttons and screens of a GUI pops
> up here. From time to time, people advocate a
> thorough description of the GUI, figuring that
> with full-text search people can find what they
> need, and what they want is to be able to find
> descriptions when they're looking at dialog boxes.
>
> My contention has always been that although learning
> styles are of course different from person to person,
> most people buy something because they want to use it
> and the documentation should tell them how. I was
> reminded of these discussions last night, when I
> wanted to find out how to create a multiple-page PDF
> with our shiny new scanner. I've provided play-by-
> play commentary so you can share my pain :->
>
> The only documentation is a searchable Help file for
> my Macintosh. First I look under "Basic Scanning,"
> where I have a choice of "Scanning with Scanner Buttons,"
> Scanning with CanoScan Toolbox," or "Sanning with ScanGear
> (Simple Mode)." I don't know the interface yet so I have
> no idea which to choose. I quickly look at each, but they
> describe each button or toolbox icon and I'm not sure
> which I need so they don't really help me.
>
> Then I search for "multipage PDF." The first hit says
> "Confirmation of the Scanned Image and Exif Settings."
> I skim the page and see a table under "Save as Type"
> with descriptions of each of the items in the related
> dialog box. Finally, in a footnote under the table, I
> see a description of the choice I need: "If you select
> [PDF (Multiple Pages)], all of the images in the display
> area are saved on separate pages in a single PDF file in
> the order in which they are displayed."
>
> Further down, I see a description of the "Save in"
> field that tells me how to set the folder to save the
> file to. But I don't see anything that tells me where
> I indicate the PDF file name, and there's no self-evident
> field in this dialog box.
>
> Back to search, to look for "file name." That takes
> me to a description of the [PDF] dialog box, which
> establishes the settings for PDF files. Sure enough,
> it has a File Name field. Further down on this page
> is a description of the "Save as Type" field and it
> provides a little more information about exactly how
> to scan a PDF with multiple pages. It's a different
> and more thorough description than the one in the
> other dialog box Help.
>
> As a user, I would have much preferred to open this
> Help file and find a list of tasks, including a task
> titled "To Create a Multiple-Page PDF File" that
> would have walked me through the process, rather than
> having to skim through dialog box descriptions located
> through the help until I found buttons or fields that
> matched the next thing I figured I had to do.
>
> -- Janice
>
> ***********************************************************
> Janice Gelb          | The only connection Sun has with
> janice -dot- gelb -at- sun -dot- com  | this message is the return address
>
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> 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 
> mikestarr-techwr-l -at- writestarr -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/mikestarr-techwr-l%40writestarr.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.
> 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.