[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/21 04:44:18

Modified files:
        UMLLink        : short-paper.rst 

Log message:
        reorg

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

Patches:
Index: manuscripts/UMLLink/short-paper.rst
diff -u manuscripts/UMLLink/short-paper.rst:1.18 
manuscripts/UMLLink/short-paper.rst:1.19
--- manuscripts/UMLLink/short-paper.rst:1.18    Wed May 21 04:25:49 2003
+++ manuscripts/UMLLink/short-paper.rst Wed May 21 04:44:17 2003
@@ -2,7 +2,7 @@
 Bridging Javadoc and design documentation via UML diagram image maps
 ====================================================================
 
-.. $Id: short-paper.rst,v 1.18 2003/05/21 08:25:49 tjl Exp $
+.. $Id: short-paper.rst,v 1.19 2003/05/21 08:44:17 tjl Exp $
 
 .. short paper == 2 pages, deadline the end of May
 
@@ -171,6 +171,14 @@
 that 
 together create a multicontext view for the element.
 
+Using UML diagrams 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. Inserting copies of each UML diagram
+in which a given class appears to its Javadoc as an imagemap
+for jumping to the other related classes
+is a good
 
 ..  Because UML diagrams should be made anyway, it is good start to
     think about using them also for navigation.
@@ -194,27 +202,18 @@
     * we do not claim that UML work as the best possible diagrams
       for documentation navigation, but it's still much better than nothing
 
-- why UML-diagrams would work as menus
+..  - why UML-diagrams would work as menus
 
-  * UMLs human made abstraction of the system containing
-    all the most relevant parts
+      * UMLs human made abstraction of the system containing
+       all the most relevant parts
 
-  * don't link to everywhere, but to the most essential places
+      * 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
+      * UMLs are already natural part of the design documentation
+       and thus, familiar to development grew reading documentation
 
-Making it easy
-==============
-
-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
+The implementation in Navidoc
+=============================
 
   * using lexical UML language
 
@@ -285,6 +284,15 @@
 - 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 [XXX],