[Gzz-commits] manuscripts/UMLLink short-paper.rst

[Tuomas J. Lukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Tuomas J. Lukka <address@hidden>        03/05/30 06:57:17

Modified files:
        UMLLink        : short-paper.rst 

Log message:
        Final twids

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/short-paper.rst.diff?tr1=1.48&tr2=1.49&r1=text&r2=text

Patches:
Index: manuscripts/UMLLink/short-paper.rst
diff -u manuscripts/UMLLink/short-paper.rst:1.48 
manuscripts/UMLLink/short-paper.rst:1.49
--- manuscripts/UMLLink/short-paper.rst:1.48    Thu May 29 13:22:18 2003
+++ manuscripts/UMLLink/short-paper.rst Fri May 30 06:57:16 2003
@@ -210,19 +210,23 @@
 a single program element often appears on several separate diagrams
 that 
 together create a multicontext view for the element.
-
-Using UML diagrams as spatial menus to jump around
+Using the UML diagrams created for the design documentation
+as spatial menus to jump around
 the documents for the different program elements 
 is attractive exactly because of this: each diagram
 in which an element appears gives some of the necessary
 context for that element. 
-Since the diagrams also appear in the design documentation,
-which is definitely related to the program elements
-described in the diagram, it should also be reachable
-through the spatial menu in the diagram --- we insert
-into the diagrams some elements that show where 
-the diagram appears in the design documentation.
-Figure 1 [ref-example]_ shows some example HTML pages produced by our system.
+
+Some screenshots illustrating this navigation paradigm are shown
+in Figure [ref-example]_.
+
+..  Since the diagrams also appear in the design documentation,
+    which is definitely related to the program elements
+    described in the diagram, it should also be reachable
+    through the spatial menu in the diagram --- we insert
+    into the diagrams some elements that show where 
+    the diagram appears in the design documentation.
+    Figure 1 [ref-example]_ shows some example HTML pages produced by our 
system.
 
 
 ..  Because UML diagrams should be made anyway, it is good start to
@@ -279,17 +283,20 @@
 .. think, this should be much clearer :) But how to say everything shortly...
 
 Navidoc, our implementation, is a light-weight tool built on top of
-several existing Free Software tools. Its main purpose is to compile
-the design documentation and UML diagrams embedded within it. 
+several existing Free Software tools. Its main function is to 
+compile
+the design documentation and UML diagrams embedded within it
+and to insert copies of the UML diagrams into the embedded documentation
+pages. 
 Navidoc uses several free utilies to convert each
-textual UML diagram description into a set of imagemaps --- one
+UML diagram into a set of imagemaps --- one
 for each target document since the current document is highlighted
-in the images. These diagrams, embedded into target documents, allow easy 
traversal
-through all the participant nodes, and they backlink to the startup page, which
-contains the original diagram.
+in the images. The diagrams allow easy traversal
+through all the participant nodes, and also contain a backlink to the design 
document page
+containing the original diagram.
 The automatically inserted images
-are scaled to half size, whereas in the original location
-in the design documentation the images are shown at their full size.
+are scaled to half size to avoid cluttering the Javadoc pages.
+
 
 .. After compiling, it creates imagemaps for every UML diagram to link
    diagrams' elements to corresponding source code documentation
@@ -327,13 +334,16 @@
     * setting layout may be more 
 
 We have found it useful to create UML diagrams using textual syntax
-embedded within documentation page originals. In software
-development groups, where programmers also write the documentation,
-the switch from programming tools to documentation tools should 
-not be a barrier to writing documentation and clarifying it with diagrams. 
+embedded into the design documentation source --- it is easier for programmers
+and our tools allows the separation of the structure and layout of the diagram.
 However, with minor modifications, Navidoc should also be usable
 when using direct manipulation GUIs to create the UML diagrams.
 
+..  In software
+    development groups, where programmers also write the documentation,
+    the switch from programming tools to documentation tools should 
+    not be a barrier to writing documentation and clarifying it with diagrams. 
+
 ..  Compared to direct manipulation drawing tools, textual
     description may feel abstract, but describing things lexically is natural 
     to programmers. 
@@ -388,14 +398,18 @@
 UML diagrams
 have been used to traverse between javadoc and design documentation.
 During three months (Jan 03 till end of Mar 03), 9% of all
-design documentation page request came by traversing from javadoc to
-design documentation via diagrams. Further, 11% of all
-javadoc visits came from design documentation using imagemapped
+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. 
 Unfortunately, the referrer logs did not allow us to 
 identify the use of UML diagrams for navigation
 within javadoc pages or within design documents, because there 
 are other links besides the UML diagrams between those pages.
+Also, we are unable to say how much of the traffic came from testing
+and debugging Navidoc itself and how much from real use.
+Anecdotally, finding the context *is* easier with the UML diagrams.
 
 
 .. We expect those number would be even higher.
@@ -419,7 +433,7 @@
 Conclusion
 ==========
 
-We have presented a navigational aid which hypertexturally connects
+We have presented a navigational aid which hypertextually connects
 two distinct areas of documentation using human-authored UML diagrams
 as spatial menus.
 Now, it is not a new idea to use UML diagrams as spatial menus ---
@@ -429,6 +443,8 @@
 Also, there has been 
 work on connecting design documentation to code 
 as well, e.g. through textual analysis [maletic03recovering]_.
+
+
 However, automatically generated diagrams and indices often include
 too much irrelevant information; human-made UML diagrams are quite different
 from automatically generated ones since they try to *express* a meaningful