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

[Troy Klukewich <tklukewich -at- sbcglobal -dot- net>]

I feel the pain.

Working in three-tier structured documentation systems
for several years now (concepts, tasks, and
reference), I have advocated the following model:

1. Provide minimalistic direction in the UI where it
makes sense
2. Provide context sensitivity at the page/screen and
dialog level (per field is overkill)
3. Provide slightly expanded content in the context
sensitivity, but more importantly, link to related
procedures or tasks
4. Link tasks to related concepts where required to
provide background context, large process
explanations, and architecture descriptions

Finally, the conceptual material itself, rather than
being geared to describing the UI or product features
should be targeted at large user goals. 

You can tackle the doc bottom-up, from UI elements, or
top-down, through conceptual documentation. Different
learning styles are accomodated.

As we move toward the self-describing UI, it is less
important for the documentation to describe every
little widget, but more important than ever to
describe the goals and tasks in which those widgets
reside.

Someone pass the Aspirin. I think I've consumed too
much UI doc again. ;-)

Troy Klukewich
Information Architect
Oracle
 

--- Janice Gelb <Janice -dot- Gelb -at- Sun -dot- COM> wrote:

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

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.