[Gzz-commits] manuscripts/UMLLink SCRATCH umllink.rst

[Asko Soukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Asko Soukka <address@hidden>    03/01/31 10:34:03

Modified files:
        UMLLink        : SCRATCH umllink.rst 

Log message:
        description of  problem

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/SCRATCH.diff?tr1=1.14&tr2=1.15&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/umllink.rst.diff?tr1=1.54&tr2=1.55&r1=text&r2=text

Patches:
Index: manuscripts/UMLLink/SCRATCH
diff -u manuscripts/UMLLink/SCRATCH:1.14 manuscripts/UMLLink/SCRATCH:1.15
--- manuscripts/UMLLink/SCRATCH:1.14    Fri Jan 31 09:04:05 2003
+++ manuscripts/UMLLink/SCRATCH Fri Jan 31 10:34:03 2003
@@ -1,4 +1,14 @@
-:Stamp: $Id: SCRATCH,v 1.14 2003/01/31 14:04:05 humppake Exp $
+:Stamp: $Id: SCRATCH,v 1.15 2003/01/31 15:34:03 humppake Exp $
+
+
+ - Perspectives to UML class diagrams, or classifiers in general:
+
+   Cook and Daniels, Designing Object Systems: Object-Oriented 
+   Modeling with Syntropy. Prentice Hall, 1994. 
+   Referred in Fowler and Scott: UML distilled,
+   2nd ed., Addison-Wesley.
+
+   XXX Couldn't find this one yet.
 
 Issues
 ------
@@ -37,6 +47,13 @@
 
 trashbin
 --------
+
+  + creating UML diagrams should be natural part our of design
+    (pegboard) and documenting (architecture docs) processes
+
+ - Include PEGs: possibly not-yet accepted or not-yet implemented proposals 
+   for architectural changes.
+
 
  - diagrams are from human to human
 
Index: manuscripts/UMLLink/umllink.rst
diff -u manuscripts/UMLLink/umllink.rst:1.54 
manuscripts/UMLLink/umllink.rst:1.55
--- manuscripts/UMLLink/umllink.rst:1.54        Fri Jan 31 09:04:05 2003
+++ manuscripts/UMLLink/umllink.rst     Fri Jan 31 10:34:03 2003
@@ -2,7 +2,7 @@
 A free software toolchain for bidirectional linking between UML diagrams and 
Javadoc
 
====================================================================================
 
-:Stamp: $Id: umllink.rst,v 1.54 2003/01/31 14:04:05 humppake Exp $
+:Stamp: $Id: umllink.rst,v 1.55 2003/01/31 15:34:03 humppake Exp $
 
 Introduction
 ============
@@ -271,17 +271,34 @@
 In addition to the tool selection problem we have to problem of two distinct
 documentation: the human written design documentation and automaticly generated
 detailed Javadoc documentation. During coding the Javadoc documentation is
-often necessary to be, but the architectural design documentation could
-be easily left in the dark reaches of the filesystem. Although, it could also 
be
-argued that architectural documents left unused because
-hard to find?
-
- + hypertext disorientation problem still exists with javadoc
-
-   disorientation: the tendency to lose
-   one's sense of location and direction in a nonlinear document;
-   1) where you are in the network 2) how to get to seom other place that
-   you know (or think) exists in the network [conklin-hypertext, pp.38-40] 
+often necessary, but the architectural design documentation could be easily 
left
+in the dark reaches of the filesystem. It could be argued that architectural 
+documents are left unused, because relevant parts linked to ongoing work are 
+hard to find. The two distinct documentation (javadoc and design documentation)
+cannot seen as whole. Therefore we should make them work as a whole.
+
+"Obvious" question: can we increase the overall value by interconnecting the 
+two distinct documentations?
+
+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 useful
+to be able to see if any design documents refer to that class.
+This is the starting point for the toolchain developed in this article.
+
+Design
+======
+
+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 document [#]_. User don't know where she is in the 
documentation 
+network or how to get to some other place that she knows to exist in the 
network.
+
+bi-directional crosslinking between those two distinct
+documentations and select a common naviational metaphor for them both.
+
+.. [#] conklin-hypertext, pp.38-40
+
+What can we link?
 
    "--individuals appear to be attempting to create cognitive
    representations of hypertext structures in the form of a survey-type
@@ -297,37 +314,6 @@
    devices would be those that are spatially based." 
    [edward-hardman-lost-in-hyperspace, p.123] 
 
-
- - Include PEGs: possibly not-yet accepted or not-yet implemented proposals 
-   for architectural changes.
-
-  + creating UML diagrams should be natural part our of design
-    (pegboard) and documenting (architecture docs) processes
-
-  + as a small group we have too small budget for
-    large tools like Rational Rose (also ideological reasons
-    to use open source, though open code is always extensible)
-
-"Obvious" question: can we increase the overall value by
-interconnecting the two? 
-
-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 useful
-to be able to see if any design documents refer to that class.
-This is the starting point for the toolchain developed in this article.
-
-Design
-======
-
-What can we link?
-
- - Perspectives to UML class diagrams, or classifiers in general:
-
-   Cook and Daniels, Designing Object Systems: Object-Oriented 
-   Modeling with Syntropy. Prentice Hall, 1994. 
-   Referred in Fowler and Scott: UML distilled,
-   2nd ed., Addison-Wesley.
 
    - Conceptual