[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gzz-commits] manuscripts/UMLLink short-paper.rst
From: |
Tuukka Hastrup |
Subject: |
[Gzz-commits] manuscripts/UMLLink short-paper.rst |
Date: |
Wed, 28 May 2003 05:51:39 -0400 |
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
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, (continued)
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Asko Soukka, 2003/05/21
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Asko Soukka, 2003/05/21
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Asko Soukka, 2003/05/21
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/21
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Asko Soukka, 2003/05/21
- [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 <=
- [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, 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