From: dannelly@eng.auburn.edu (R. Stephen Dannelly)
Newsgroups: fj.mail-lists.x-window
Subject: GUI Documentation Question
Date: 27 Aug 92 04:10:35 GMT
Distribution: fj
Organization: Auburn University Engineering

Date: Wed, 26 Aug 1992 19:00:32 GMT
Message-Id: <1992Aug26.190032.29817@news.duc.auburn.edu>
Newsgroups: comp.software-eng,comp.windows.x


I have a question concerning an area (GUI documentation) that I
don't know a lot about.  I hope this is not a stupid post.


BACKGROUND:
===========
    For the last couple of years I have been managing our department's
Senior Design course.  We get projects from various sources and assign
a group of four students to work on the project for two quarters.
They take their project through the traditional water fall life
cycle of requirements, design, and implementation.  They generate
a large amount of documentation -- from scope of the product, to
DFDs, Data Dictionaries, user guides, ...  -- the entire nine yards.


PROBLEM:
========
    Many of the projects involve the development of large Graphical
User Interfaces.  The students generally either build the interface 
using X or an X based tool.  The problem encountered is that it is 
very difficult to fully document a GUI. (Insert standard Software 
Engineering justifications for good documentation here.)  GUI programs 
tend to be code creating the windows and a seemingly unconnected collection 
of functions that handle events, manipulate the graphical output through
extensive library calls, and traditional data handling procedures.
    I have done some searching through books on the development of user
interfaces and have not found anything useful on the documentation of 
GUIs.  The emphasis is on design issues such as color, know your user, 
how to build good help, etc...
    Here are some of the problems we have:
          how to specify what the windows look like
          how to specify the user dialogue
          how to specify every operation that can be performed in a window
          how to show how each window relates to each other
          how to indicate which functions are called by which actions
Interface designers seem to have come up with specification techniques
for most of these individually, but no all inclusive documentation 
technique appears to be present.


OUR PATCH-WORK SOLUTION
=======================
    We have adopted a loose style for the documentation of such projects.
Drawings (or screen dumps) of each window form the backbone.  Each picture
is followed by an english description of its general function.  This is 
then followed by a widget tree.  Next comes structure charts which tend to
be very unconnected.  Finally, for each window, the pseudo-code for each
function that is called by that window.  Following the window descriptions 
is a data dictionary.
    The screen dumps and widget trees handle the appearance of the windows, 
however, constraints and resources must be inferred instead of specifically
specified.  The text descriptions handle the dialogue and listing of 
operations.  As far as processing of graphical control and call backs, 
well, that must be inferred from the structure charts and pseudo-code.
Of course, all of this is a patchwork of techniques that is not always
precise.


QUESTION
========
    Does there exist a comprehensive GUI documentation technique?  
Any names of books or articles relating to this would be appreciated.
I would also GREATLY appreciate ANY comments or suggestions.  Real
life experiences would be nice as well.


---------------------------------------------------------------------
R. Stephen Dannelly                          Auburn University
dannelly@eng.auburn.edu	                     Computer Science & Eng
                                             Auburn, AL  USA  36830