/[gzz]/manuscripts/UMLLink/short-paper.rst
ViewVC logotype

Diff of /manuscripts/UMLLink/short-paper.rst

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.48 by tjl, Thu May 29 17:22:18 2003 UTC revision 1.49 by tjl, Fri May 30 10:57:16 2003 UTC
# Line 210  Therefore Line 210  Therefore
210  a single program element often appears on several separate diagrams  a single program element often appears on several separate diagrams
211  that  that
212  together create a multicontext view for the element.  together create a multicontext view for the element.
213    Using the UML diagrams created for the design documentation
214  Using UML diagrams as spatial menus to jump around  as spatial menus to jump around
215  the documents for the different program elements  the documents for the different program elements
216  is attractive exactly because of this: each diagram  is attractive exactly because of this: each diagram
217  in which an element appears gives some of the necessary  in which an element appears gives some of the necessary
218  context for that element.  context for that element.
219  Since the diagrams also appear in the design documentation,  
220  which is definitely related to the program elements  Some screenshots illustrating this navigation paradigm are shown
221  described in the diagram, it should also be reachable  in Figure [ref-example]_.
222  through the spatial menu in the diagram --- we insert  
223  into the diagrams some elements that show where  ..  Since the diagrams also appear in the design documentation,
224  the diagram appears in the design documentation.      which is definitely related to the program elements
225  Figure 1 [ref-example]_ shows some example HTML pages produced by our system.      described in the diagram, it should also be reachable
226        through the spatial menu in the diagram --- we insert
227        into the diagrams some elements that show where
228        the diagram appears in the design documentation.
229        Figure 1 [ref-example]_ shows some example HTML pages produced by our system.
230    
231    
232  ..  Because UML diagrams should be made anyway, it is good start to  ..  Because UML diagrams should be made anyway, it is good start to
# Line 279  The implementation in Navidoc Line 283  The implementation in Navidoc
283  .. think, this should be much clearer :) But how to say everything shortly...  .. think, this should be much clearer :) But how to say everything shortly...
284    
285  Navidoc, our implementation, is a light-weight tool built on top of  Navidoc, our implementation, is a light-weight tool built on top of
286  several existing Free Software tools. Its main purpose is to compile  several existing Free Software tools. Its main function is to
287  the design documentation and UML diagrams embedded within it.  compile
288    the design documentation and UML diagrams embedded within it
289    and to insert copies of the UML diagrams into the embedded documentation
290    pages.
291  Navidoc uses several free utilies to convert each  Navidoc uses several free utilies to convert each
292  textual UML diagram description into a set of imagemaps --- one  UML diagram into a set of imagemaps --- one
293  for each target document since the current document is highlighted  for each target document since the current document is highlighted
294  in the images. These diagrams, embedded into target documents, allow easy traversal  in the images. The diagrams allow easy traversal
295  through all the participant nodes, and they backlink to the startup page, which  through all the participant nodes, and also contain a backlink to the design document page
296  contains the original diagram.  containing the original diagram.
297  The automatically inserted images  The automatically inserted images
298  are scaled to half size, whereas in the original location  are scaled to half size to avoid cluttering the Javadoc pages.
299  in the design documentation the images are shown at their full size.  
300    
301  .. After compiling, it creates imagemaps for every UML diagram to link  .. After compiling, it creates imagemaps for every UML diagram to link
302     diagrams' elements to corresponding source code documentation     diagrams' elements to corresponding source code documentation
# Line 327  in the design documentation the images a Line 334  in the design documentation the images a
334      * setting layout may be more      * setting layout may be more
335    
336  We have found it useful to create UML diagrams using textual syntax  We have found it useful to create UML diagrams using textual syntax
337  embedded within documentation page originals. In software  embedded into the design documentation source --- it is easier for programmers
338  development groups, where programmers also write the documentation,  and our tools allows the separation of the structure and layout of the diagram.
 the switch from programming tools to documentation tools should  
 not be a barrier to writing documentation and clarifying it with diagrams.  
339  However, with minor modifications, Navidoc should also be usable  However, with minor modifications, Navidoc should also be usable
340  when using direct manipulation GUIs to create the UML diagrams.  when using direct manipulation GUIs to create the UML diagrams.
341    
342    ..  In software
343        development groups, where programmers also write the documentation,
344        the switch from programming tools to documentation tools should
345        not be a barrier to writing documentation and clarifying it with diagrams.
346    
347  ..  Compared to direct manipulation drawing tools, textual  ..  Compared to direct manipulation drawing tools, textual
348      description may feel abstract, but describing things lexically is natural      description may feel abstract, but describing things lexically is natural
349      to programmers.      to programmers.
# Line 388  Statistics from the WWW server of our pr Line 398  Statistics from the WWW server of our pr
398  UML diagrams  UML diagrams
399  have been used to traverse between javadoc and design documentation.  have been used to traverse between javadoc and design documentation.
400  During three months (Jan 03 till end of Mar 03), 9% of all  During three months (Jan 03 till end of Mar 03), 9% of all
401  design documentation page request came by traversing from javadoc to  design documentation page requests resulted from traversing from the Javadoc pages to
402  design documentation via diagrams. Further, 11% of all  design documentation via UML diagrams, and 11% of all
403  javadoc visits came from design documentation using imagemapped  Javadoc page requests resulted from traversing from design documentation to the Javadoc pages
404    using the imagemapped
405  diagrams.  diagrams.
406  Unfortunately, the referrer logs did not allow us to  Unfortunately, the referrer logs did not allow us to
407  identify the use of UML diagrams for navigation  identify the use of UML diagrams for navigation
408  within javadoc pages or within design documents, because there  within javadoc pages or within design documents, because there
409  are other links besides the UML diagrams between those pages.  are other links besides the UML diagrams between those pages.
410    Also, we are unable to say how much of the traffic came from testing
411    and debugging Navidoc itself and how much from real use.
412    Anecdotally, finding the context *is* easier with the UML diagrams.
413    
414    
415  .. We expect those number would be even higher.  .. We expect those number would be even higher.
# Line 419  are other links besides the UML diagrams Line 433  are other links besides the UML diagrams
433  Conclusion  Conclusion
434  ==========  ==========
435    
436  We have presented a navigational aid which hypertexturally connects  We have presented a navigational aid which hypertextually connects
437  two distinct areas of documentation using human-authored UML diagrams  two distinct areas of documentation using human-authored UML diagrams
438  as spatial menus.  as spatial menus.
439  Now, it is not a new idea to use UML diagrams as spatial menus ---  Now, it is not a new idea to use UML diagrams as spatial menus ---
# Line 429  inheritance trees for navigation within Line 443  inheritance trees for navigation within
443  Also, there has been  Also, there has been
444  work on connecting design documentation to code  work on connecting design documentation to code
445  as well, e.g. through textual analysis [maletic03recovering]_.  as well, e.g. through textual analysis [maletic03recovering]_.
446    
447    
448  However, automatically generated diagrams and indices often include  However, automatically generated diagrams and indices often include
449  too much irrelevant information; human-made UML diagrams are quite different  too much irrelevant information; human-made UML diagrams are quite different
450  from automatically generated ones since they try to *express* a meaningful  from automatically generated ones since they try to *express* a meaningful

Legend:
Removed from v.1.48  
changed lines
  Added in v.1.49

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26