Re: User interface elements as a section itself in manuals

Subject: Re: User interface elements as a section itself in manuals
From: Bruce Boyer <bboyer -at- OBJECTSHARE -dot- COM>
Date: Wed, 4 Nov 1998 09:50:40 -0800

At 09:35 AM 11/4/98 -0800, Karen Field wrote:
>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

There is much to be said about this approach to documentation, but in
general your intuitions are correct, it's unnecessary.

Early on, before personal workstations were common, exhaustively
"documenting the screens" was useful because odds were the reader
would not be at a terminal while working through the manual. This
is not generally the case anymore.

Often, continuing this practice is due to the need for a writer to
do something, and documenting the screens is a straight forward activity.
It also adds page count. Usually, however, it's not useful information.

Perhaps the best argument you can use for getting away from this bunch
of filler is to point out that, at least if the GUI is done well, the
dialogs *ARE* the documentation. Repeating the instructions which are
already built into the interface is simply redundant.


************
Bruce Boyer, Ph.D.
Lead Technical Writer
ObjectShare
email: bboyer -at- objectshare -dot- com
************

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




Previous by Author: Re: Code Documentation
Next by Author: Re: ANON: Writing a Tutorial
Previous by Thread: Re: User interface elements as a section itself in manuals
Next by Thread: Re: User interface elements as a section itself in manuals


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


Sponsored Ads