[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gzz-commits] manuscripts/UMLLink short-paper.rst
From: |
Tuomas J. Lukka |
Subject: |
[Gzz-commits] manuscripts/UMLLink short-paper.rst |
Date: |
Thu, 29 May 2003 12:00:36 -0400 |
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
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, (continued)
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Asko Soukka, 2003/05/22
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/22
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Asko Soukka, 2003/05/23
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/26
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuukka Hastrup, 2003/05/28
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuukka Hastrup, 2003/05/28
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuukka Hastrup, 2003/05/28
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuukka Hastrup, 2003/05/28
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/28
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/29
- [Gzz-commits] manuscripts/UMLLink short-paper.rst,
Tuomas J. Lukka <=
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/29
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/29
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/30
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/30
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/30
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/30
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/30
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/30