home *** CD-ROM | disk | FTP | other *** search
/ NetNews Usenet Archive 1992 #19 / NN_1992_19.iso / spool / comp / software / 3305 < prev    next >
Encoding:
Internet Message Format  |  1992-08-26  |  3.9 KB
  1. Xref: sparky comp.software-eng:3305 comp.windows.x:15671
  2. Path: sparky!uunet!dtix!darwin.sura.net!news.duc.auburn.edu!eng.auburn.edu!dannelly
  3. From: dannelly@eng.auburn.edu (R. Stephen Dannelly)
  4. Newsgroups: comp.software-eng,comp.windows.x
  5. Subject: GUI Documentation Question
  6. Message-ID: <1992Aug26.190032.29817@news.duc.auburn.edu>
  7. Date: 26 Aug 92 19:00:32 GMT
  8. Sender: dannelly@eng.auburn.edu (Robert S. Dannelly)
  9. Organization: Auburn University Engineering
  10. Lines: 71
  11. Nntp-Posting-Host: willow.cse.eng.auburn.edu
  12.  
  13.  
  14. I have a question concerning an area (GUI documentation) that I
  15. don't know a lot about.  I hope this is not a stupid post.
  16.  
  17.  
  18. BACKGROUND:
  19. ===========
  20.     For the last couple of years I have been managing our department's
  21. Senior Design course.  We get projects from various sources and assign
  22. a group of four students to work on the project for two quarters.
  23. They take their project through the traditional water fall life
  24. cycle of requirements, design, and implementation.  They generate
  25. a large amount of documentation -- from scope of the product, to
  26. DFDs, Data Dictionaries, user guides, ...  -- the entire nine yards.
  27.  
  28.  
  29. PROBLEM:
  30. ========
  31.     Many of the projects involve the development of large Graphical
  32. User Interfaces.  The students generally either build the interface 
  33. using X or an X based tool.  The problem encountered is that it is 
  34. very difficult to fully document a GUI. (Insert standard Software 
  35. Engineering justifications for good documentation here.)  GUI programs 
  36. tend to be code creating the windows and a seemingly unconnected collection 
  37. of functions that handle events, manipulate the graphical output through
  38. extensive library calls, and traditional data handling procedures.
  39.     I have done some searching through books on the development of user
  40. interfaces and have not found anything useful on the documentation of 
  41. GUIs.  The emphasis is on design issues such as color, know your user, 
  42. how to build good help, etc...
  43.     Here are some of the problems we have:
  44.           how to specify what the windows look like
  45.           how to specify the user dialogue
  46.           how to specify every operation that can be performed in a window
  47.           how to show how each window relates to each other
  48.           how to indicate which functions are called by which actions
  49. Interface designers seem to have come up with specification techniques
  50. for most of these individually, but no all inclusive documentation 
  51. technique appears to be present.
  52.  
  53.  
  54. OUR PATCH-WORK SOLUTION
  55. =======================
  56.     We have adopted a loose style for the documentation of such projects.
  57. Drawings (or screen dumps) of each window form the backbone.  Each picture
  58. is followed by an english description of its general function.  This is 
  59. then followed by a widget tree.  Next comes structure charts which tend to
  60. be very unconnected.  Finally, for each window, the pseudo-code for each
  61. function that is called by that window.  Following the window descriptions 
  62. is a data dictionary.
  63.     The screen dumps and widget trees handle the appearance of the windows, 
  64. however, constraints and resources must be inferred instead of specifically
  65. specified.  The text descriptions handle the dialogue and listing of 
  66. operations.  As far as processing of graphical control and call backs, 
  67. well, that must be inferred from the structure charts and pseudo-code.
  68. Of course, all of this is a patchwork of techniques that is not always
  69. precise.
  70.  
  71.  
  72. QUESTION
  73. ========
  74.     Does there exist a comprehensive GUI documentation technique?  
  75. Any names of books or articles relating to this would be appreciated.
  76. I would also GREATLY appreciate ANY comments or suggestions.  Real
  77. life experiences would be nice as well.
  78.  
  79.  
  80. ---------------------------------------------------------------------
  81. R. Stephen Dannelly                          Auburn University
  82. dannelly@eng.auburn.edu                         Computer Science & Eng
  83.                                              Auburn, AL  USA  36830
  84.