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

[Tuomas J. Lukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Tuomas J. Lukka <address@hidden>        03/05/20 15:29:51

Modified files:
        UMLLink        : short-paper.rst 

Log message:
        shorten,edit

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

Patches:
Index: manuscripts/UMLLink/short-paper.rst
diff -u manuscripts/UMLLink/short-paper.rst:1.12 
manuscripts/UMLLink/short-paper.rst:1.13
--- manuscripts/UMLLink/short-paper.rst:1.12    Tue May 20 15:18:25 2003
+++ manuscripts/UMLLink/short-paper.rst Tue May 20 15:29:51 2003
@@ -2,7 +2,7 @@
 Bridging Javadoc and design documentation via UML diagram image maps
 ====================================================================
 
-.. $Id: short-paper.rst,v 1.12 2003/05/20 19:18:25 tjl Exp $
+.. $Id: short-paper.rst,v 1.13 2003/05/20 19:29:51 tjl Exp $
 
 .. short paper == 2 pages, deadline the end of May
 
@@ -77,22 +77,27 @@
 the design documentation and the embedded documentation.
 This can be daunting to a newcomer; consider the javadoc
 for the interface ``java.security.PublicKey`` in Sun's
-Java2 SDK 1.4.1 at
-``http://java.sun.com/j2se/1.4.1/docs/api/java/security/PublicKey.html``.
-XXXREF
+Java2 SDK 1.4.1
+XXXREF.
 While the class is easy to find through the package and class lists
 when looking for a class to represent cryptographical public keys,
 the javadoc is not terribly useful: there is no information
 there on how one may create objects that implement this interface.
 The only way to find this out is to click on the ``Use`` link
 which lists all the occurrences of this class as method
-return values or parameters.
+return values or parameters, without much contextual information
+about the importance of the methods.
 However, what would really help would be a link to the design
-documentation, even just a UML diagram of what the intended
+documentation, even just a diagram of what the intended
 uses or lifespans of classes implementing this interface
-are and how one creates them.
+are and how one creates them. 
+These diagrams certainly exist for all properly managed 
+medium-to-large scale software projects --- the problem is getting
+them to where it matters.
 
-In this article, we discuss Navidoc: a system that, given design
+.. at ``http://java.sun.com/j2se/1.4.1/docs/api/java/security/PublicKey.html``.
+
+In this article, we introduce Navidoc: a system that, given design
 documentation with marked-up UML diagrams, inserts the UML
 diagrams into the classes' javadocs to function as spatial menus.
 
@@ -145,21 +150,28 @@
 [booch-jacobson-rumbaugh98uml-user-guide]_. As a standard it is a
 natural part of software design documentation, because it functions as
 a common language for communication within a software development
-team. Because UML diagrams should be made anyway, it is good start to
-think about using them also for navigation.
-
-The usability of hypertext-based documentation is said to might suffer
-from user's disorientation: the tendency to lose one's sense of
-location and direction in a nonlinear documents
-[conklin87hypertext-onpage-38-40]_. It is also said that the most
-appropriate types of navigation devices should be based on spatiality
-to allow users to develop a cognitive map of the data structure before
-moving within it [edwards-hardman89lost-in-hyperspace-onpage-123]_.
+team. Each UML diagram is meant to expose a particular aspect
+of the design. 
+Therefore
+a single program element may appear on several distinct diagrams, 
+that 
+together create a multicontext view for the element.
+
+
+..  Because UML diagrams should be made anyway, it is good start to
+    think about using them also for navigation.
+    (said in intro now)
+
+..  The usability of hypertext-based documentation may suffer
+    from user's disorientation: the tendency to lose one's sense of
+    location and direction in a nonlinear documents
+    [conklin87hypertext-onpage-38-40]_. It is also said that the most
+    appropriate types of navigation devices should be based on spatiality
+    to allow users to develop a cognitive map of the data structure before
+    moving within it [edwards-hardman89lost-in-hyperspace-onpage-123]_.
 
 Besides UML diagrams are spatial, they are encouraged to be
-complementary [booch-jacobson-rumbaugh98uml-user-guide-10]_. Therefore
-a single element may appear in several distinct diagrams, that all
-together create a multicontext view for the element. ...
+complementary 
 
 .. multicontext views versus traditional hierarchical documentation
  
@@ -171,9 +183,12 @@
       for documentation navigation, but it's still much better than nothing
 
 - why UML-diagrams would work as menus
+
   * UMLs human made abstraction of the system containing
     all the most relevant parts
+
   * don't link to everywhere, but to the most essential places
+
   * UMLs are already natural part of the design documentation
     and thus, familiar to development grew reading documentation