Re: HELP! Guidelines/methodology for documenting GUI software

[Mary Anthony <mary -at- PERSISTENCE -dot- COM>]

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

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
tasks:

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.

Good Luck,

Mary







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