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