/[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.34 by tjl, Thu May 22 14:15:36 2003 UTC revision 1.35 by humppake, Fri May 23 12:24:11 2003 UTC
# Line 162  diagrams into the classes' javadocs to f Line 162  diagrams into the classes' javadocs to f
162  ..  raw:: latex  ..  raw:: latex
163    
164      \begin{figure*}      \begin{figure*}
165        \label{example}
166      \begin{centering}      \begin{centering}
167      \includegraphics[height=9cm]{short-trav-1.gen.eps}\hskip .4cm%      \includegraphics[height=9cm]{short-trav-1.gen.eps}\hskip .4cm%
168      \includegraphics[height=9cm]{short-trav-4.gen.eps}\hskip .4cm%      \includegraphics[height=9cm]{short-trav-4.gen.eps}\hskip .4cm%
# Line 260  The implementation in Navidoc Line 261  The implementation in Navidoc
261    
262  .. think, this should be much clearer :) But how to say everything shortly...  .. think, this should be much clearer :) But how to say everything shortly...
263    
264  Navidoc, our implementation, is as a light-weight tool built on top of  Navidoc, our implementation, is a light-weight tool built on top of
265  several existing Free Software tools. Its main purpose is to compile  several existing Free Software tools. Its main purpose is to compile
266  the design documentation and UML diagrams embedded within it.  the design documentation and UML diagrams embedded within it.
267  Navidoc uses several free utilies to convert each  Navidoc uses several free utilies to convert each
268  textual UML diagram description into a set of imagemaps --- one  textual UML diagram description into a set of imagemaps --- one
269  for each target document since the current document is highlighted  for each target document since the current document is highlighted
270  in the images. These diagrams embedded into target documents, allow easy traverse  in the images. These diagrams embedded into target documents, allow easy traverse
271  through all the participant nodes and backlink to the startup page holding  through all the participant nodes and backlink to the startup page, which
272  the original diagram.  contains the original diagram.
273  The automatically inserted images  The automatically inserted images
274  are scaled to half size, whereas in their "real" location  are scaled to half size, whereas in their "real" location
275  in the design documentation the images are shown at their full size.  in the design documentation the images are shown at their full size.
# Line 308  in the design documentation the images a Line 309  in the design documentation the images a
309    
310      * setting layout may be more      * setting layout may be more
311    
312  We've it found useful to create UML diagrams using textual syntax  We have found it useful to create UML diagrams using textual syntax
313  embedded within documentation page originals. In small softaware  embedded within documentation page originals. In small softaware
314  development groups, where programmers also write the documentation,  development groups, where programmers also write the documentation,
315  the documentation tools shouldn't be gap to change the programming  switching programming tool to documentation tools should not be a
316  tool to document writing tools. Textual UML diagram description, of  barrier to write documentation and clarify it with diagrams. Textual
317  course, can be written with any text editor. Comparing with any direct  UML diagram description, of course, can be written with any text
318  manipulation drawing tool, textual description may feel abstract at  editor. Comparing with direct manipulation drawing tools, textual
319  first, but the when users are programmers it could be even more  description may feel a bit abstract, but for programmers it
320  natural for them to describe things lexically.  could be very natural to describe things lexically.
321    
322  .. Also at least for a  .. Also at least for a
323     programmer, who are used to describe objects lexically, describing     programmer, who are used to describe objects lexically, describing
# Line 360  natural for them to describe things lexi Line 361  natural for them to describe things lexi
361  Experiences  Experiences
362  ===========  ===========
363    
364  The statistics of our projects WWW server show that diagrams  The statistics of our project's WWW server show that diagrams
365  connecting javadoc to design documentationg have increased the usage  connecting javadoc to design documentationg have significantly
366  of project's design documentation and traversing between documentation  increased the usage of project's design documentation and traversing
367  levels is very common. In the period of three months (Jan 03 till end  between documentation levels. Altough, we couldn't distuinguish usage
368  of Mar 03) at least 9% of all design documentation page request came  of design documentation's or javadoc's internal navigation from usage
369  by traversing from javadoc to design documentation via diagrams. On  of imagemapped diagrams, we could track the usage of diagrams, when
370  the other hand at least 11% of all javadoc visits came from design  browsing between design documentation and javadoc.
371  documentation via diagrams.  
372    In the period of three months (Jan 03 till end of Mar 03) 9% of all
373    design documentation page request came by traversing from javadoc to
374    design documentation via diagrams. On the other hand 11% of all
375    javadoc visits came from design documentation using imagemapped
376    diagrams.
377    
378    .. , how much usage of UML diagrams
379       as spatial menus replace usage of documentation's internal navigation.
380    
381    
382  ..   * WWW statistics from himalia: 2003/01 - 2003/03  ..   * WWW statistics from himalia: 2003/01 - 2003/03
383    
# Line 382  documentation via diagrams. Line 392  documentation via diagrams.
392  Conclusion  Conclusion
393  ==========  ==========
394    
395    We have presented a navigational aid, which hypertexturally connects
396    two distinct areas of documentation, using human-authored UML diagrams
397    as spatial menus.
398    
399  It is not a new idea to use UML diagrams in documentation  It is not a new idea to use UML diagrams in documentation
400  navigation. There already exists Javadoc like documentation generation  navigation. There already exists Javadoc like documentation generation
401  tools, which generate automaticly classdiagrams from program source  tools, which generate automaticly class diagrams from program source
402  code to help navigation in generated documentation.  code to help navigation inside the generated documentation.
403  Doxygen [heesch03doxygen]_,  [heesch03doxygen]_, for example, generates diagrams of class
 for example, generates diagrams of class  
404  inheritance tree for that purpose.  inheritance tree for that purpose.
405    
406    Our approach is different, since we prefer fully human created
407    diagrams in our design documentation. We want to avoid being bloated
408    by a large amount of too detailed diagrams, which are often resulted
409    by generators interpreting only the source code. On the other hand,
410    recently there has been promising work based on textual analysis of
411    connectable documentations [maletic03recovering]_. XXX need for the
412    last sentence :).
413    
414    .. Of course, generated documentation may give well detailed information
415       from the current implementation, but the design documentation should
416       also cover the future and be rather well abstracted than well
417       detailed. Therefore, we want to avoid being bloated by a large amount
418       of too detailed diagrams (meanless for us) and prefer fully human
419       created diagrams in our design documentation.
420    
421    
422    .. Our approach is different from most tools,
423       which rely more on automatically generated links [maletic03recovering]_,
424       or inserting connections to the source code [devanbu99chime]_.
425    
426    
427    
428  .. - other analysis software  .. - other analysis software
429    
430  .. - autogen not comparable to design doc  .. - autogen not comparable to design doc
431    
 Of course, generated documentation may give well detailed information  
 from the current implementation, but the design documentation should  
 also cover the future and be rather well abstracted than well  
 detailed. Therefore, we want to avoid being bloated by a large amount  
 of too detailed diagrams (meanless for us) and prefer fully human  
 created diagrams in our design documentation.  
432                                                                                                                            
433  .. - how are UMLs embedded into documentation  .. - how are UMLs embedded into documentation
434    
 Our approach is different from most tools,  
 which rely more on automatically generated links [maletic03recovering]_,  
 or inserting connections to the source code [devanbu99chime]_.  
435    
436  .. - future  .. - future
437      * fenfire      * fenfire

Legend:
Removed from v.1.34  
changed lines
  Added in v.1.35

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