[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: |
Fri, 30 May 2003 06:57:17 -0400 |
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
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, (continued)
- [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, 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/29
- [Gzz-commits] manuscripts/UMLLink short-paper.rst,
Tuomas J. Lukka <=
- [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