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

[Asko Soukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Asko Soukka <address@hidden>    03/04/30 10:20:41

Modified files:
        UMLLink        : short-paper.rst 

Log message:
        some

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

Patches:
Index: manuscripts/UMLLink/short-paper.rst
diff -u manuscripts/UMLLink/short-paper.rst:1.3 
manuscripts/UMLLink/short-paper.rst:1.4
--- manuscripts/UMLLink/short-paper.rst:1.3     Thu Apr 24 07:53:20 2003
+++ manuscripts/UMLLink/short-paper.rst Wed Apr 30 10:20:41 2003
@@ -2,7 +2,7 @@
 Bridging Javadoc and design documentation via UML diagram image maps
 ====================================================================
 
-.. $Id: short-paper.rst,v 1.3 2003/04/24 11:53:20 humppake Exp $
+.. $Id: short-paper.rst,v 1.4 2003/04/30 14:20:41 humppake Exp $
 
 .. short paper == 2 pages, deadline the end of May
 
@@ -37,16 +37,43 @@
 =========
 
 - short description about problem:
-  * programming language specific tools generate 
-    well linked but distinct documentations from source code
-  * above all is human written abstraction to the system
+  * programming language specific tools like javadoc do generate 
+    well navigable documentations from source code
+  * above them is a human written abstraction to the system
     as whole - the design documentation
   * how to make these documentation fragments interconnected
     with each other with minimum additional work
+ 
+  Should be searched previous papers, which have research
+  quostions alike. Check at first the keywords given by referees
+  of UMLLink article.
+
+The usability of xhypertext-based documentation may suffer from user's
+disorientation: the tendency to lose one's sense of location and
+direction in a nonlinear document
+[conklin87hypertext-onpage-38-40]_. This means that users don't know
+where they are in the documentation network or how to get to some
+other place that they know to exist in the network.
 
 - resolving:
   * connecting distinct fragments together using design
     documentation's UML diagrams
+  * bidirectional linking
+  * several context views (different UML diagrams), multimenu
+    * spatial navigation (within the diagram)
+
+Javadoc [friendly95javadoc]_ is a detailed and fully generated
+documentation from javadoc comments of each class and method in the
+Java source code.
+
+Edwards and Hardman [edwards-hardman89lost-in-hyperspace]_ argue that
+the most appropriate types of navigation devices would be based on
+spatiality. According to their research, individuals appear to be
+attempting to create cognitive representations of hypertext structures
+in the form of a survey-type map. They conlude that users should be
+allowed to develop a cognitive map of one view of the data structure
+before being given the opinion of navigating through the data some
+other way [edwards-hardman89lost-in-hyperspace-onpage-123]_.
 
 - why UML
   * UML is de facto standard for describing software architecture
@@ -55,6 +82,25 @@
   * we do not claim that UML work as the best possible diagrams
     for documentation navigation, but it's still much better than nothing
 
+In this article we focus on the more conventional use of UML
+to plan and document software 
+architecture on a general level. 
+UML can function as a common language for 
+communication within a software development team, and for this purpose 
+we prefer human-drawn (non-autogenerated) diagrams that show the semantically 
+meaningful features at the right level of abstraction:
+
+The distinct pieces (Javadoc and the design documentation) cannot seen as a 
+whole. The obvious question, then, is: can we increase the overall value by 
+hyperlinking the two distinct pieces of documentation? 
+
+When looking at a design document, jumping to the Javadocs to get the
+details would be useful, and when looking at a Javadoc, it would be
+most useful to be able to see if any design documents discuss that class
+or package.
+We believe that the design documentation would be read more if 
+made easily reachable from relevant parts of Javadoc. 
+
 - why UML-diagrams would work as menus
   * UMLs human made abstraction of the system containing
     all the most relevant parts
@@ -96,3 +142,5 @@
 
 - future
   * fenfire
+
+.. bibliography:: gzigzag