GUI Documentation

[Janice Gelb <janiceg -at- MARVIN -dot- ENG -dot- SUN -dot- COM>]

Regarding the GUI Documentation question raised by Julie Tholen:

Beth Agnew made a lot of the points that I would have made on this
issue. As you will be able to tell by the caveats below, I am
heartily against screen-by-screen, field-by-field GUI documentation.

My first caveat is to make sure your engineers don't talk you into
adding a lot of text about *how* the product does something. I call
this the difference between "The Joys of SuperTool" vs. "Using
SuperTool." By and large, the general user audience does not care, for
example, *how* a search engine searches for a document, they just want
to know what button to push and what text to enter to find what they
want.

Also, try to avoid describing the interface more than necessary. For
example, if your product only has pop-up menus, you don't have to
include the modifier "pop-up" every time you talk about a menu. Just
because the design team has come up with cool names for every part of
the screen, you don't have to use them if the instruction is clear
without it. For example, I just edited a book about a product where the
main screen featured four large icons that took you to different areas
of the product. The design team called the area "the system topology"
but there was no reason the user had to be told "click the Message
Center in the system topology" when "click the Message Center icon" was
perfectly clear.

Emphasize what the user is trying to do rather than how they do it. For
example, a common task statement is "Choose Print from the File menu to
open the Print dialog box." Well, users are not doing this in order to
see the dialog box; they're doing it so they can print. Avoiding
language like this, petty though it may seem, may help you focus your
writing on helping the user accomplish the task at hand. not describing
the interface at every step.

Finally, keep in mind how you yourself usually behave when you buy a
product with a GUI. Do you read through the conceptual explanations
that were painstakingly crafted by one of your peers at that company?
Do you do everything in the order in which it is presented in the book,
so you know what context you're in based on the preceding task?

The answer is usually "no"! Most of us buy a product, use the docs to
install it (if we're good :-> ), and then try to do stuff with it. If
we get stuck, we look in the index, go directly to the task for what we
want to do, skim it, and go on with our jobs. As we do, so do our
users...

-- Janice

********************************************************************************
Janice Gelb                  | The only connection Sun has with this
janice -dot- gelb -at- eng -dot- sun -dot- com      | message is the return address.
http://www.geocities.com/Area51/8018/index.html

"The Web is the world's greatest library with all the books on the floor"
                                         -- Patrick Casey, AP (Oklahoma)

********************************************************************************

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html