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

[Tuukka Hastrup]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Tuukka Hastrup <address@hidden> 03/05/28 05:51:39

Modified files:
        UMLLink        : short-paper.rst 

Log message:
        more small rewordings

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

Patches:
Index: manuscripts/UMLLink/short-paper.rst
diff -u manuscripts/UMLLink/short-paper.rst:1.38 
manuscripts/UMLLink/short-paper.rst:1.39
--- manuscripts/UMLLink/short-paper.rst:1.38    Wed May 28 05:16:07 2003
+++ manuscripts/UMLLink/short-paper.rst Wed May 28 05:51:39 2003
@@ -87,7 +87,7 @@
 
 .. REF for j2sdk - probably no room.... XXX
 
-What is often missing is the connections between
+Often missing are the connections between
 the design documentation and the embedded documentation.
 This can be daunting to a newcomer; consider the javadoc
 in Sun's Java2 SDK 1.4.1
@@ -97,20 +97,20 @@
 the javadoc is not terribly useful: it lacks the information
 there on how to create objects that implement this interface.
 Currently, the only relevant links are on an accompanying ``Use`` page,
-which lists all the occurrences of this class elsewhere in the 
+which lists all the references to this interface elsewhere in the 
 documentation.
 Further, those lists lack information about the contextual importance of 
-the methods --- the methods for 
+the mentionings --- the methods for 
 creating a ``PublicKey`` are listed alongside eg. the methods
 that return a ``PublicKey`` contained in another object.
 
 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 diagrams certainly exist for all properly managed 
+These architectural diagrams certainly 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
-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``.
 
@@ -199,12 +199,12 @@
 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 on the design documentation,
+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
-elements showing the location where the diagram appears
-in the design documentation into the diagrams as well.
+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.
 
 
@@ -267,11 +267,11 @@
 Navidoc uses several free utilies to convert each
 textual UML diagram description 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 
traverse
-through all the participant nodes and backlink to the startup page, which
+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.
 The automatically inserted images
-are scaled to half size, whereas in their "real" location
+are scaled to half size, whereas in the original location
 in the design documentation the images are shown at their full size.
 
 .. After compiling, it creates imagemaps for every UML diagram to link
@@ -310,14 +310,15 @@
     * setting layout may be more 
 
 We have found it useful to create UML diagrams using textual syntax
-embedded within documentation page originals. In small softaware
+embedded within documentation page originals. In software
 development groups, where programmers also write the documentation,
-switching programming tool to documentation tools should not be a
-barrier to write documentation and clarify it with diagrams. Textual
-UML diagram description, of course, can be written with any text
-editor. Comparing with direct manipulation drawing tools, textual
-description may feel a bit abstract, but for programmers it
-could be very natural to describe things lexically.
+the switch from programming tools to documentation tools should 
+not be a
+barrier to writing documentation and clarifying it with diagrams. Textual
+UML diagram description can naturally be written with any text
+editor. Compared to direct manipulation drawing tools, textual
+description may feel abstract, but describing things lexically is natural 
+to programmers. 
 
 .. Also at least for a
    programmer, who are used to describe objects lexically, describing
@@ -361,19 +362,18 @@
 Experiences
 ===========
 
-The statistics of our project's WWW server show that diagrams
-connecting javadoc to design documentationg have been used
-for traversing
-between the documentation levels. 
-In the period of three months (Jan 03 till end of Mar 03) 9% of all
+Statistics from our project's WWW server show that 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. On the other hand 11% of all
+design documentation via diagrams. Further, 11% of all
 javadoc visits came from design documentation using imagemapped
 diagrams. 
-Unfortunately, the HTTP server logs did not allow us to 
-distinguish the use of the UML diagrams for navigation
-from one javadoc page to another or from one design document
-to another so we have no data on that --- we expect the number
+
+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 those groups 
+have other links as well. We expect those number
 would be even higher.
 
 .. Anecdotally XXX
@@ -401,8 +401,8 @@
 It is not a new idea to use UML diagrams in documentation
 navigation. For example, Doxygen [heesch03doxygen]_ automatically
 generates class
-inheritance tree for navigation inside the embedded documentation.
-There has also been work on connecting the design documentation and
+inheritance trees for navigation within the embedded documentation.
+Previous work also exists on connecting the design documentation and
 program code through textual analysis [maletic03recovering]_.
 However, automatically generated diagrams and indices often include
 too much irrelevant information; human-made UML diagrams are quite different
@@ -410,8 +410,8 @@
 the system's semantics.
 
 What is new in our approach is the use of UML diagrams from the design
-documentation and their insertion to the relevant Javadoc / other embedded
-documentation pages as spatial menus allowing traversal between the design
+documentation and their insertion to the relevant Javadoc or other embedded
+documentation pages as spatial menus, allowing traversal between the design
 documentation and the Javadoc pages.
 
 .. Of course, generated documentation may give well detailed information