Re: User interface elements as a section itself in manuals

[Thomas Quine <thomas -dot- quine -at- NCOMPASSLABS -dot- COM>]

A busy user only opens documentation to answer the question, "How do I
do what it is I have to do?" Therefore, good documentation is
task-oriented.
In task-oriented documentation, there are only two components:
instructions, and the prerequisite knowledge required to carry out those
instructions.
In your example, knowledge of GUI interface components may be a
prerequisite to carrying out instructions, and therefore must be
presented to the user.
But the ideal is to place the unit of knowledge as close as possible to
the instruction, even, if possible, embedded into the instruction.
Otherwise you run the risk of the reader skipping over important
prerequisite information in their haste to do what it is they have to
do.
If you don't burden the reader with unnecessary information, they will
come to trust your documentation, and won't skip essential sections,
cursing "this useless manual" as they go.
Good luck!
- Thom


-----Original Message-----
From: Karen Field [mailto:KarenF -at- TRITECH -dot- COM]
Sent: Wednesday, November 04, 1998 9:35 AM
To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
Subject: User interface elements as a section itself in manuals


I work as an editor and writer in software documentation, and I need
some
feedback. Some of my clients are fond of including an entire section in
end-user manuals devoted to describing the dialog boxes, screens, and
other
UI elements the user encounters in a program. For example, after a
section
describing how to do a task, a section follows entitled "Dialog Box
Information" that describes in painful detail each field/check
box/whatever
in each dialog box.

To me, this seems to overburden the user. When I open a software manual,
I'm
looking for a specific task, and I don't care what UI elements I
encounter
as long as Iknow what to do when I get there in the procedure itself.

Can anyone enlighten me on how this is useful to the user? If you agree
with
me, please offer your reasoning as well. You can reply to me directly if
you
like: karenf -at- tritech -dot- com

Thanks.

Karen Field
Technical Writer/Editor/Indexer

 =======================================================================
===

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=