Re: GUI documentation

Subject: Re: GUI documentation
From: "Susan W. Gallagher" <sgallagher -at- EXPERSOFT -dot- COM>
Date: Tue, 22 Jul 1997 11:38:42 -0700

At 08:57 AM 7/22/97 -0500, Julie Tholen wrote:
>... I would like to hear from others who
>have dealt with GUI before.
>
>...From what I have
>seen, the user manuals fall into two camps: first, page after page of
>screen captures illustrating what the user is looking at on their tube,
>with somewhat explanatory field text; or second, a starting point
>screen capture, with field by field identification and definition.
>
>Both ways seem dissatisfying to me. How do you handle GUI?

Julie,

Documenting a GUI can be tricky. It's difficult to achieve just
the right amount of explanation. Here's what I do:

Create an overview section that explains all the menu options
and toolbar buttons. This section can be all a power-user needs
to get up and running and can serve as a handy reference once
the beginner gains experience. Doesn't much matter whether you
put this section up front or at the end.

Additionally, use this section to explain all of the implemented
user affordances (like drag and drop, double clicking, and accelerator
keys). Once you've told the user these affordances have been implemented
in the program, forget about them. The one thing that will drive both
you and your user toward a marked propensity for lip-diddling is an
attempt to explain every way there is to accomplish a task in a GUI.
Experienced users will find and use them; new users won't want to
know about them quite yet.

Make the rest of the book task based. I generally take a consistent
approach of:
* Defining the task and discussing its repercussions
* Enumerating the steps required to accomplish the task

Years ago, I'd also list the field information in the user manual.
Nowadays, that stuff goes in the context sensitive help, so I leave
it out of the paper book.

As to screen shots -- well there are several schools of though, but I
belong to the "fewer is better" club. Quite some years ago, I read of
a study that showed docs with screenshots inhibited information
retention. A trainer friend of mine said "sure! show 'em the screen
on paper, they'll never look at the 'puter!" Still, others rely on
screenshots, so YMMV, know your audience, yadayadayada. ;-)

You may want to consider using partial screenshots to highlight
the significant portion of the screen (i.e., the area under discussion).


-Sue Gallagher http://pw1.netcom.com/~gscale/susanwg/
sgallagher -at- expersoft -dot- com http://www.expersoft.com

The _Guide_ is definitive.
Reality is frequently inaccurate. --Douglas Adams

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


Previous by Author: Re: Insecure about browser terminology
Next by Author: Re: Long Summary: Good Interview Questions
Previous by Thread: Re: GUI documentation
Next by Thread: Re: GUI documentation


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


Sponsored Ads