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: HELP! Guidelines/methodology for documenting GUI software
Subject:Re: HELP! Guidelines/methodology for documenting GUI software From:Mary Anthony <mary -at- PERSISTENCE -dot- COM> Date:Thu, 12 Sep 1996 13:33:32 -0700
At 07:24 AM 9/12/96 MST, Robert Tennant wrote:
>Robert Tennant asked about ways to approach the documentation of a system
>with very busy screens. He says,
>The approach I've taken is to put a screen shot into the manual and then
>to carve it up into "fields," describing each field in detail.
Robert, this seems to be a method many people fall back on, at least judging
by the number of books I've seen structured this way. You are right, this
isn't the best way but some times it is the most expedient. IMO, the best
way to document a GUI's fields, menus, and screens is with good online help.
An example is the F1 help in Word -- the user presses F1 and the system
responds with a help pointer. Then, the user selects the field, button -
whatever -- of interest. The system responds with specific help about the
field. When this type of help is available to the user there is little need
to provide exhaustive hardcopy reference documentation for each screen, each
screen's menu, and so forth.
Now, the Word-type help is not available for all people. But there other
types of ways to do very similar things in most windowing environments --
Motif, OpenLook, and X-Windows. In my experience, this often involves
writing help hooks in the code that display the appropriate help.
You might want to talk to your engineers to find out if this is available.
>Unfortunately, the system is not structured in a way that easily lends
>itself to documenting simple functional tasks (like How to Open Your File, How
>to Do Thus and So, How to Print Your Data, etc.).
>However, the whole system is
>driven by screens containing buttons that the operator clicks, drop-down
>menus that contain secondary cascading menus, etc., etc.,etc.
If a user is exploring a system like a geographer, then they are going
through it and asking:
What is this?
Where does this go?
You are answering those questions with your "geography lessons." However,
most users are not explorers. They bought the system to accomplish
particular tasks. I would try thinking up the questions a user would ask
when trying to accomplish these tasks and then documenting "the answers."
Sometimes even seemingly simple questions can lead to several documentation
How do I create a Cross Reference with Frame?
Requires the user to understand many concepts and procedures in Frame. So,
I would document:
the concept of a cross-reference
how to create a cross-reference format (in case they don't have any yet)
how to insert a cross-reference into text
the concept of an "out of date" reference
how to update a "bad" reference
and so forth. Essentially, this is a task analysis -- what tasks would the
user like to accomplish, what must the user know to begin, and what must
the user have to accomplish the tasks.
"What I read, I forget; what I see, I remember; what I do, I learn."
- Unknown Dressage Master
Mary Anthony mary -at- persistence -dot- com
Searchable archives located at http://www.documentation.com/
ALL questions or problems concerning the list
should go to the listowner, Eric Ray at ejray -at- ionet -dot- net -dot-