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

[Asko Soukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Asko Soukka <address@hidden>    03/05/23 08:24:11

Modified files:
        UMLLink        : short-paper.rst 

Log message:
        slightly too long

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

Patches:
Index: manuscripts/UMLLink/short-paper.rst
diff -u manuscripts/UMLLink/short-paper.rst:1.34 
manuscripts/UMLLink/short-paper.rst:1.35
--- manuscripts/UMLLink/short-paper.rst:1.34    Thu May 22 10:15:36 2003
+++ manuscripts/UMLLink/short-paper.rst Fri May 23 08:24:11 2003
@@ -162,6 +162,7 @@
 ..  raw:: latex
 
     \begin{figure*}
+    \label{example}
     \begin{centering}
     \includegraphics[height=9cm]{short-trav-1.gen.eps}\hskip .4cm%
     \includegraphics[height=9cm]{short-trav-4.gen.eps}\hskip .4cm%
@@ -260,15 +261,15 @@
 
 .. think, this should be much clearer :) But how to say everything shortly...
 
-Navidoc, our implementation, is as a light-weight tool built on top of
+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. 
 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 holding
-the original diagram.
+through all the participant nodes and backlink to the startup page, which
+contains the original diagram.
 The automatically inserted images
 are scaled to half size, whereas in their "real" location
 in the design documentation the images are shown at their full size.
@@ -308,15 +309,15 @@
 
     * setting layout may be more 
 
-We've it found useful to create UML diagrams using textual syntax
+We have found it useful to create UML diagrams using textual syntax
 embedded within documentation page originals. In small softaware
 development groups, where programmers also write the documentation,
-the documentation tools shouldn't be gap to change the programming
-tool to document writing tools. Textual UML diagram description, of
-course, can be written with any text editor. Comparing with any direct
-manipulation drawing tool, textual description may feel abstract at
-first, but the when users are programmers it could be even more
-natural for them to describe things lexically.
+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.
 
 .. Also at least for a
    programmer, who are used to describe objects lexically, describing
@@ -360,14 +361,23 @@
 Experiences
 ===========
 
-The statistics of our projects WWW server show that diagrams
-connecting javadoc to design documentationg have increased the usage
-of project's design documentation and traversing between documentation
-levels is very common. In the period of three months (Jan 03 till end
-of Mar 03) at least 9% of all design documentation page request came
-by traversing from javadoc to design documentation via diagrams. On
-the other hand at least 11% of all javadoc visits came from design
-documentation via diagrams.
+The statistics of our project's WWW server show that diagrams
+connecting javadoc to design documentationg have significantly
+increased the usage of project's design documentation and traversing
+between documentation levels. Altough, we couldn't distuinguish usage
+of design documentation's or javadoc's internal navigation from usage
+of imagemapped diagrams, we could track the usage of diagrams, when
+browsing between design documentation and javadoc.
+
+In the period of 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
+javadoc visits came from design documentation using imagemapped
+diagrams. 
+
+.. , how much usage of UML diagrams
+   as spatial menus replace usage of documentation's internal navigation.
+
 
 ..   * WWW statistics from himalia: 2003/01 - 2003/03
 
@@ -382,30 +392,46 @@
 Conclusion
 ==========
 
+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. There already exists Javadoc like documentation generation
-tools, which generate automaticly classdiagrams from program source
-code to help navigation in generated documentation. 
-Doxygen [heesch03doxygen]_,
-for example, generates diagrams of class
+tools, which generate automaticly class diagrams from program source
+code to help navigation inside the generated documentation.
+[heesch03doxygen]_, for example, generates diagrams of class
 inheritance tree for that purpose.
 
+Our approach is different, since we prefer fully human created
+diagrams in our design documentation. We want to avoid being bloated
+by a large amount of too detailed diagrams, which are often resulted
+by generators interpreting only the source code. On the other hand,
+recently there has been promising work based on textual analysis of
+connectable documentations [maletic03recovering]_. XXX need for the
+last sentence :).
+
+.. Of course, generated documentation may give well detailed information
+   from the current implementation, but the design documentation should
+   also cover the future and be rather well abstracted than well
+   detailed. Therefore, we want to avoid being bloated by a large amount
+   of too detailed diagrams (meanless for us) and prefer fully human
+   created diagrams in our design documentation.
+
+
+.. Our approach is different from most tools,
+   which rely more on automatically generated links [maletic03recovering]_,
+   or inserting connections to the source code [devanbu99chime]_.
+
+
+
 .. - other analysis software
 
 .. - autogen not comparable to design doc
 
-Of course, generated documentation may give well detailed information
-from the current implementation, but the design documentation should
-also cover the future and be rather well abstracted than well
-detailed. Therefore, we want to avoid being bloated by a large amount
-of too detailed diagrams (meanless for us) and prefer fully human
-created diagrams in our design documentation.
                                                             
 .. - how are UMLs embedded into documentation
 
-Our approach is different from most tools,
-which rely more on automatically generated links [maletic03recovering]_,
-or inserting connections to the source code [devanbu99chime]_.
 
 .. - future
     * fenfire