TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
************
