[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/29 12:00:36

Modified files:
        UMLLink        : short-paper.rst 

Log message:
        More twids - still too long

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

Patches:
Index: manuscripts/UMLLink/short-paper.rst
diff -u manuscripts/UMLLink/short-paper.rst:1.45 
manuscripts/UMLLink/short-paper.rst:1.46
--- manuscripts/UMLLink/short-paper.rst:1.45    Thu May 29 05:27:03 2003
+++ manuscripts/UMLLink/short-paper.rst Thu May 29 12:00:36 2003
@@ -161,31 +161,29 @@
 
 ..  raw:: latex
 
-    \begin{figure*}
-    \label{example}
-    \begin{centering}
+    \begin{figure*}%
+    \begin{centering}%
     \includegraphics[height=9cm]{short-trav-3.gen.eps}\hskip .4cm%
     \includegraphics[height=9cm]{short-trav-1.gen.eps}\hskip .4cm%
     \includegraphics[height=9cm]{short-trav-4.gen.eps}\hskip .4cm%
-    \end{centering}
+    \end{centering}%
     \caption{Three HTML pages modified by Navidoc.
-    The left and center pages are Javadoc pages into which the UML
-    diagrams have been automatically added by Navidoc at half size.
-    The right-hand page is a part of the design documentation for
-    those interfaces.
-    The Javadoc pages are for classes which appear
-    in the UML diagram on the design documentation page.
+    \label{example}
+    The left and center pages are Javadocs particular interfaces and
+    the right-hand page is a part of the design documentation for
+    those interfaces, which contains a UML diagram 
+    on which the two interfaces described by the Javadoc pages appear.
     Reduced copies of this diagram have been added to both Javadoc pages.
-    The elements in the diagram are active: clicking on the Scrollblock
+    The elements in the diagrams are active: clicking on the Scrollblock
     element in any of the diagrams takes the user to the Scrollblock
-    javadoc page.
+    javadoc.
     Traversing
     to the design document works by clicking the heading at the
     top of the diagram.
-    In each version of the diagram, the element corresponding to
+    In each version of the UML diagram,
     the currently active node is highlighted both with color 
     and a distinctive thick, irregular line to catch the viewer's eye.
-    }
+    }%
     \end{figure*}
 
 ..  The diagram works as 
@@ -386,19 +384,21 @@
 Experiences
 ===========
 
-Statistics from our project's WWW server show that diagrams
+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 request came by traversing from javadoc to
 design documentation via diagrams. Further, 11% of all
 javadoc visits came from design documentation using 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 those groups 
-have other links as well. We expect those number
-would be even higher.
+within javadoc pages or within design documents, because there 
+are other links besides the UML diagrams between those pages.
+
+
+.. We expect those number would be even higher.
 
 .. Anecdotally XXX
 
@@ -419,24 +419,28 @@
 Conclusion
 ==========
 
-We have presented a navigational aid, which hypertexturally connects
-two distinct areas of documentation, using human-authored UML diagrams
+We have presented a navigational aid which hypertexturally connects
+two distinct areas of documentation using human-authored UML diagrams
 as spatial menus.
-It is not a new idea to use UML diagrams in documentation
-navigation. For example, Doxygen [heesch03doxygen]_ automatically
+Now, it is not a new idea to use UML diagrams as spatial menus ---
+for example, Doxygen [heesch03doxygen]_ automatically
 generates class
 inheritance trees for navigation within the embedded documentation.
-Design documentation has been connected to
-program code as well, through textual analysis [maletic03recovering]_.
+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 part of
+from automatically generated ones since they try to *express* a meaningful
+part of
 the system's semantics.
-
-New in our approach is the use of UML diagrams from 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.
+What is 
+new in our approach is the use of human-made UML diagrams from the design
+documentation as spatial menus
+on the relevant Javadoc or other embedded
+documentation pages, allowing traversal between the design
+documentation and the Javadoc pages as well as giving the user an
+idea of the context of the current class.
 
 .. Of course, generated documentation may give well detailed information
    from the current implementation, but the design documentation should