/[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.57 by tjl, Mon Jul 21 12:39:19 2003 UTC revision 1.58 by tjl, Mon Jul 21 13:19:47 2003 UTC
# Line 74  architectural views on a more general le Line 74  architectural views on a more general le
74  the source code usually contains  the source code usually contains
75  embedded documentation, such as Javadoc [friendly95javadoc]_, giving details on the concrete  embedded documentation, such as Javadoc [friendly95javadoc]_, giving details on the concrete
76  classes and methods.  classes and methods.
   
 .. Since these parts of documentation are semantically dependent  
    they should be interlinked together.  
   
77  The generation of easily navigable hypertext  The generation of easily navigable hypertext
78  from the embedded documentation is essentially  from the embedded documentation is essentially
79  a solved problem  a solved problem
# Line 104  when looking for a class representing cr Line 100  when looking for a class representing cr
100  the javadoc is not terribly useful: it lacks the information  the javadoc is not terribly useful: it lacks the information
101  on how to create objects that implement this interface.  on how to create objects that implement this interface.
102  The only relevant links are on an accompanying ``Use`` page,  The only relevant links are on an accompanying ``Use`` page,
103  which lists all the references to this interface in any method  without any context: the methods for
 prototypes elsewhere in the  
 documentation.  
 The list does not give information about the contextual importance of  
 the items --- the methods for  
104  creating a ``PublicKey`` are listed alongside the accessor methods  creating a ``PublicKey`` are listed alongside the accessor methods
105  that return a ``PublicKey`` contained in another, unrelated object.  that return a ``PublicKey`` contained in another, unrelated object.
106    
107    .. at ``http://java.sun.com/j2se/1.4.1/docs/api/java/security/PublicKey.html``.
108    
109  Far more helpful would be a link to the design  Far more helpful would be a link to the design
110  documentation, even just a diagram showing the intended  documentation, even just a diagram showing the intended
111  uses or lifespans of related objects and how one creates the objects.  uses or lifespans of related objects and how one creates the objects.
112  These architectural diagrams certainly exist for all properly managed  These architectural diagrams are
113    certain to *already exist* for all properly managed
114  medium-to-large scale software projects --- the problem is getting  medium-to-large scale software projects --- the problem is getting
115  them to where it matters without having to manually insert  them to where it matters without having to manually insert
116  the links into the low-level documentation.  the links into the low-level documentation.
   
 .. at ``http://java.sun.com/j2se/1.4.1/docs/api/java/security/PublicKey.html``.  
   
117  In this article, we introduce Navidoc: a system that, given design  In this article, we introduce Navidoc: a system that, given design
118  documentation with marked-up UML diagrams, inserts the UML  documentation with marked-up UML diagrams, inserts the UML
119  diagrams into the classes' javadocs to function as spatial menus.  diagrams into the classes' javadocs to function as spatial menus.
# Line 224  the documents for the different program Line 216  the documents for the different program
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  Some screenshots illustrating this navigation paradigm are shown  Some screenshots illustrating this navigation paradigm are shown
220  in Figure [ref-example]_.  in Figure [ref-example]_.
221    
# Line 289  in Figure [ref-example]_. Line 280  in Figure [ref-example]_.
280  .. think, this should be much clearer :) But how to say everything shortly...  .. think, this should be much clearer :) But how to say everything shortly...
281    
282  Navidoc, our implementation, is a light-weight tool built on top of  Navidoc, our implementation, is a light-weight tool built on top of
283  existing Free Software tools. Its main function is to  existing Free Software tools.
 compile  
 the design documentation and the UML diagrams embedded within it  
 and to insert copies of the UML diagrams into the embedded documentation  
 pages.  
284  Navidoc converts each  Navidoc converts each
285  UML diagram into a set of imagemaps --- one  UML diagram into a set of imagemaps --- one
286  for each target document since the current document is highlighted  for each target document since the current document is highlighted
287  in the images. The diagrams allow easy traversal  in the images and inserts them into the relevant documents.
288  through all the participant nodes, and also contain a backlink to the design document page  The diagrams allow easy traversal
289    through all the participant nodes,
290    and also contain a backlink to the design document page
291  containing the original diagram.  containing the original diagram.
292  The automatically inserted images  The automatically inserted images
293  are scaled to half size to avoid cluttering the Javadoc pages.  are scaled to half size to avoid cluttering the Javadoc pages.
294    
295    ..  Its main function is to
296        compile
297        the design documentation and the UML diagrams embedded within it
298        and to insert copies of the UML diagrams into the embedded documentation
299        pages.
300    
301    
302  .. After compiling, it creates imagemaps for every UML diagram to link  .. After compiling, it creates imagemaps for every UML diagram to link
303     diagrams' elements to corresponding source code documentation     diagrams' elements to corresponding source code documentation
# Line 339  are scaled to half size to avoid clutter Line 334  are scaled to half size to avoid clutter
334    
335      * setting layout may be more      * setting layout may be more
336    
337  We have found it useful to create UML diagrams using textual syntax  ..  We have found it useful to create UML diagrams using textual syntax
338  embedded into the design documentation source --- it is easier for programmers,      embedded into the design documentation source --- it is easier for programmers,
339  and our tools allows the separation of the structure and layout of the diagram.      and our tools allows the separation of the structure and layout of the diagram.
340  However, with minor modifications, Navidoc should also be usable      However, with minor modifications, Navidoc should also be usable
341  when using direct manipulation GUIs to create the UML diagrams.      when using direct manipulation GUIs to create the UML diagrams.
342    
343  ..  In software  ..  In software
344      development groups, where programmers also write the documentation,      development groups, where programmers also write the documentation,
# Line 400  when using direct manipulation GUIs to c Line 395  when using direct manipulation GUIs to c
395  Experiences  Experiences
396  ===========  ===========
397    
398    We have found navidoc useful in our free software project family,
399    the most important aspect being the value added to the Javadoc pages.
400    Anecdotally, reaching the right documentation and understanding the context
401    and interrelations between classes is easier.
402    
403  Statistics from the WWW server of our project show that the  Statistics from the WWW server of our project show that the
404  UML diagrams  UML diagrams
405  have been used to traverse between javadoc and design documentation.  have been used to traverse between javadoc and design documentation (approx. 10%
406  During three months (Jan 03 till end of Mar 03), 9% of all  of traversals).
 design documentation page requests resulted from traversing from the Javadoc pages to  
 design documentation via UML diagrams, and 11% of all  
 Javadoc page requests resulted from traversing from design documentation to the Javadoc pages  
 using the imagemapped  
 diagrams.  
407  Unfortunately, the referrer logs did not allow us to  Unfortunately, the referrer logs did not allow us to
408  identify the use of UML diagrams for navigation  identify the use of UML diagrams for navigation
409  within javadoc pages or within design documents, because there  within javadoc pages or within design documents, because there
410  are other links besides the UML diagrams between those pages.  are other links besides the UML diagrams between those pages ---
411    this is a serious problem since anecdotally the UML diagrams are used to traverse
412    between Javadoc pages more often than to design documentation: a common
413    navigation technique appears to be to flick quickly between the Javadoc pages
414    and then possibly read the deeper data in the design documentation.
415    
416    
417  Also, we are unable to say how much of the traffic came from testing  Also, we are unable to say how much of the traffic came from testing
418  and debugging Navidoc itself and how much from real use.  and debugging Navidoc itself and how much from real use.
419  Anecdotally, finding the context *is* easier with the UML diagrams.  
420    ..  During three months (Jan 03 till end of Mar 03), 9% of all
421        design documentation page requests resulted from traversing from the Javadoc pages to
422        design documentation via UML diagrams, and 11% of all
423        Javadoc page requests resulted from traversing from design documentation to the Javadoc pages
424        using the imagemapped
425        diagrams.
426    
427    
428  .. We expect those number would be even higher.  .. We expect those number would be even higher.
# Line 463  documentation pages, allowing traversal Line 470  documentation pages, allowing traversal
470  documentation and the Javadoc pages as well as giving the user an  documentation and the Javadoc pages as well as giving the user an
471  idea of the context of the current class.  idea of the context of the current class.
472    
473  So far in our experience Navidoc has proven to be a most useful tool;  ..  So far, Navidoc has proven to be a most useful tool;
474  not only for improving the Javadoc navigability but also giving the design      not only for improving the Javadoc navigability but also giving the design
475  documentation writer an added incentive to create UML diagrams.      documentation writer an added incentive to create UML diagrams.
476    
477  .. Of course, generated documentation may give well detailed information  .. Of course, generated documentation may give well detailed information
478     from the current implementation, but the design documentation should     from the current implementation, but the design documentation should

Legend:
Removed from v.1.57  
changed lines
  Added in v.1.58

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