Re: User interface elements as a section itself in manuals

[Martha J Davidson <editrix -at- SLIP -dot- NET>]

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.

That's exactly the kind of information I want in the online help.  When I
have a dialog box in front of me and I need more information about what to
enter in a field, or what the implications are if I select a particular
check box, I want to click a Help button and see everything I can about
what these things mean before I make a mistake.  I'm not the sort who just
blithely tries stuff to "see what will happen."  Rather, if I'm not sure
about something and whether it will change something irretrievably, I'm
more likely to just forget it and maybe not be able to do something a help
screen would have made possible.

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

I agree that this is less useful in a paper document, but I wouldn't rule
out the usefulness of the information itself in the proper context.

martha

--
Martha Jane {Kolman | Davidson}
mailto:editrix -at- slip -dot- net

"If I am not for myself, who will be for me?
 If I am only for myself, what am I?
 If not now, when?"
        --Hillel, "Mishna, Sayings of the Fathers 1:13"

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