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

[Tuomas J. Lukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Branch:         
Changes by:     Tuomas J. Lukka <address@hidden>        03/07/21 09:19:47

Modified files:
        UMLLink        : REVIEW short-paper.rst 

Log message:
        Focus change, shorten. PLEASE READ

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

Patches:
Index: manuscripts/UMLLink/REVIEW
diff -u manuscripts/UMLLink/REVIEW:1.1 manuscripts/UMLLink/REVIEW:1.2
--- manuscripts/UMLLink/REVIEW:1.1      Wed Jul  9 13:50:33 2003
+++ manuscripts/UMLLink/REVIEW  Mon Jul 21 09:19:46 2003
@@ -1,3 +1,8 @@
+Changes for poster website paper:
+
+    - move focus away from implementation and towards results
+
+------------------------------
 
 I am sorry to inform you that your submission
 (paper 174, Bridging  Javadoc and design documentation via UML diagram image 
maps)
Index: manuscripts/UMLLink/short-paper.rst
diff -u manuscripts/UMLLink/short-paper.rst:1.57 
manuscripts/UMLLink/short-paper.rst:1.58
--- manuscripts/UMLLink/short-paper.rst:1.57    Mon Jul 21 08:39:19 2003
+++ manuscripts/UMLLink/short-paper.rst Mon Jul 21 09:19:47 2003
@@ -74,10 +74,6 @@
 the source code usually contains
 embedded documentation, such as Javadoc [friendly95javadoc]_, giving details 
on the concrete
 classes and methods.
-
-.. Since these parts of documentation are semantically dependent
-   they should be interlinked together.
-
 The generation of easily navigable hypertext 
 from the embedded documentation is essentially
 a solved problem 
@@ -104,24 +100,20 @@
 the javadoc is not terribly useful: it lacks the information
 on how to create objects that implement this interface.
 The only relevant links are on an accompanying ``Use`` page,
-which lists all the references to this interface in any method 
-prototypes elsewhere in the 
-documentation.
-The list does not give information about the contextual importance of 
-the items --- the methods for 
+without any context: the methods for 
 creating a ``PublicKey`` are listed alongside the accessor methods
 that return a ``PublicKey`` contained in another, unrelated object.
 
+.. at ``http://java.sun.com/j2se/1.4.1/docs/api/java/security/PublicKey.html``.
+
 Far more helpful would be a link to the design
 documentation, even just a diagram showing the intended
 uses or lifespans of related objects and how one creates the objects.
-These architectural diagrams certainly exist for all properly managed 
+These architectural diagrams are 
+certain to *already exist* for all properly managed 
 medium-to-large scale software projects --- the problem is getting
 them to where it matters without having to manually insert
 the links into the low-level documentation.
-
-.. at ``http://java.sun.com/j2se/1.4.1/docs/api/java/security/PublicKey.html``.
-
 In this article, we introduce Navidoc: a system that, given design
 documentation with marked-up UML diagrams, inserts the UML
 diagrams into the classes' javadocs to function as spatial menus.
@@ -224,7 +216,6 @@
 is attractive exactly because of this: each diagram
 in which an element appears gives some of the necessary
 context for that element. 
-
 Some screenshots illustrating this navigation paradigm are shown
 in Figure [ref-example]_.
 
@@ -289,20 +280,24 @@
 .. think, this should be much clearer :) But how to say everything shortly...
 
 Navidoc, our implementation, is a light-weight tool built on top of
-existing Free Software tools. Its main function is to 
-compile
-the design documentation and the UML diagrams embedded within it
-and to insert copies of the UML diagrams into the embedded documentation
-pages. 
+existing Free Software tools. 
 Navidoc converts each
 UML diagram into a set of imagemaps --- one
 for each target document since the current document is highlighted
-in the images. The diagrams allow easy traversal
-through all the participant nodes, and also contain a backlink to the design 
document page
+in the images and inserts them into the relevant documents. 
+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 to avoid cluttering the Javadoc pages.
 
+..  Its main function is to 
+    compile
+    the design documentation and the UML diagrams embedded within it
+    and to insert copies of the UML diagrams into the embedded documentation
+    pages. 
+
 
 .. After compiling, it creates imagemaps for every UML diagram to link
    diagrams' elements to corresponding source code documentation
@@ -339,11 +334,11 @@
 
     * setting layout may be more 
 
-We have found it useful to create UML diagrams using textual syntax
-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.
+..  We have found it useful to create UML diagrams using textual syntax
+    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,
@@ -400,22 +395,34 @@
 Experiences
 ===========
 
+We have found navidoc useful in our free software project family,
+the most important aspect being the value added to the Javadoc pages.
+Anecdotally, reaching the right documentation and understanding the context
+and interrelations between classes is easier.
+
 Statistics from the WWW server of our project show that the 
 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 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. 
+have been used to traverse between javadoc and design documentation (approx. 
10%
+of traversals).
 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.
+are other links besides the UML diagrams between those pages --- 
+this is a serious problem since anecdotally the UML diagrams are used to 
traverse
+between Javadoc pages more often than to design documentation: a common 
+navigation technique appears to be to flick quickly between the Javadoc pages
+and then possibly read the deeper data in the design documentation.
+
+
 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.
+
+..  During three months (Jan 03 till end of Mar 03), 9% of all
+    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. 
 
 
 .. We expect those number would be even higher.
@@ -463,9 +470,9 @@
 documentation and the Javadoc pages as well as giving the user an
 idea of the context of the current class.
 
-So far in our experience Navidoc has proven to be a most useful tool;
-not only for improving the Javadoc navigability but also giving the design
-documentation writer an added incentive to create UML diagrams.
+..  So far, Navidoc has proven to be a most useful tool;
+    not only for improving the Javadoc navigability but also giving the design
+    documentation writer an added incentive to create UML diagrams.
 
 .. Of course, generated documentation may give well detailed information
    from the current implementation, but the design documentation should