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

[Asko Soukka]

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

Modified files:
        UMLLink        : SCRATCH umllink.rst 
Added files:
        UMLLink        : .cvsignore 

Log message:
        reorg

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/.cvsignore?rev=1.1
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/SCRATCH.diff?tr1=1.7&tr2=1.8&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/umllink.rst.diff?tr1=1.42&tr2=1.43&r1=text&r2=text

Patches:
Index: manuscripts/UMLLink/SCRATCH
diff -u manuscripts/UMLLink/SCRATCH:1.7 manuscripts/UMLLink/SCRATCH:1.8
--- manuscripts/UMLLink/SCRATCH:1.7     Thu Jan 23 02:59:45 2003
+++ manuscripts/UMLLink/SCRATCH Thu Jan 23 10:55:10 2003
@@ -1,5 +1,14 @@
-:Stamp: $Id: SCRATCH,v 1.7 2003/01/23 07:59:45 tjl Exp $
-:Last-Modified: $Date: 2003/01/23 07:59:45 $
+:Stamp: $Id: SCRATCH,v 1.8 2003/01/23 15:55:10 humppake Exp $
+
+Some critics against direct manipulation:
+
+The Anti-Mac interface
+Don Gentner , Jakob Nielsen
+Communications of the ACM August 1996
+Volume 39 Issue 8 
+
+http://doi.acm.org/10.1145/232014.232032 
+
 
    + and if design documentation is outdated some particular classes
      maybe don't even exist anymore!
Index: manuscripts/UMLLink/umllink.rst
diff -u manuscripts/UMLLink/umllink.rst:1.42 
manuscripts/UMLLink/umllink.rst:1.43
--- manuscripts/UMLLink/umllink.rst:1.42        Thu Jan 23 08:37:00 2003
+++ manuscripts/UMLLink/umllink.rst     Thu Jan 23 10:55:10 2003
@@ -2,13 +2,13 @@
 A free software toolchain for bidirectional linking between UML diagrams and 
Javadoc
 
====================================================================================
 
-:Stamp: $Id: umllink.rst,v 1.42 2003/01/23 13:37:00 tjl Exp $
-:Last-Modified: $Date: 2003/01/23 13:37:00 $
+:Stamp: $Id: umllink.rst,v 1.43 2003/01/23 15:55:10 humppake Exp $
 
 Issues
 ======
 
-- How much should we talk about *our* process, how much about processes in 
general?
+- How much should we talk about *our* process, how much about
+  processes in general?
   OTOH, talking more about us makes it more personal but may make it
   also seem less relevant to others' efforts.
 
@@ -25,7 +25,8 @@
     off to a sufficient degree that we should really have to criticize
     them.
 
-- How should we discuss WYSIWYG, WYSIAYG for reST &c? Someone will surely ask 
about that,
+- How should we discuss WYSIWYG, WYSIAYG for reST &c? Someone will
+  surely ask about that,
 
     PARTIAL RESOLUTION: 
 
@@ -38,14 +39,15 @@
   is better than too detailed, automaticly up-to dated 
   and reverse engineered diagram.
 
+
+- how rational rose links diagrams into code and documentation?
  
 Introduction
 ============
 
 UML, the blah, has recently become blah blah
 
-UML book (Booch, Jacobson, Rumbaugh)
-p.24:: 
+UML book [booch-jacobson-rumbaugh-uml-used-guide, p.24]:: 
 
     "You draw diagrams to visualize a system from different
     perspectives, so a diagram is a projection into a system.
@@ -55,9 +57,9 @@
 Recently, various approaches have been developed towards
 unifying software architecture design and code (REFS)
 
- * and why they seem to end up generating either the documentation
-   from the code or the code from the documentation (antont's note about
-   duplication of data problem)
+ * they seem to end up generating either the documentation
+   from the code or the code from the documentation 
+   (antont's note about duplication of data problem)
 
 In this article, we present the tools we developed
 for using UML diagrams as multiple-ended hyperlinks
@@ -70,17 +72,15 @@
 Software development processes
 ------------------------------
 
-- our development process seems to be closing Boehm's spiral model [#]_
-  of software development, though our spiral is endless and we
-  have probably several of them running simultaneously :)
-
-.. [#] Boehm, B. (1988). "A spiral model for software development and 
-       enhancement". IEEE Computer 21 (5), pp. 61-72.
+- our development process seems to be closing Boehm's spiral model
+  [boehm-spiral-model] of software development(, though our spiral is
+  endless and we have probably several of them running simultaneously)
 
 - architectural documents are important parts of design,
   redesign and maintenance phases of the design process
 
-  + faking a rational design process [#]_ (pp. 252-255):
+  + faking a rational design process
+    [parnas-clements-rational, pp.252-255]:
   
     A) establish and document requirements
     B) design and document the module structure
@@ -91,20 +91,17 @@
     G) maintain (redesign and redevelopment, keeping documentation
        up-to-date).
 
-  + creating UML diagrams to natural part of our design (pegboard) and
-    documenting (architecture docs) process
+  + creating UML diagrams should be natural part our of design
+    (pegboard) and documenting (architecture docs) processes
 
-  + too small budget for large tools like Rational Rose
+  + 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)
      
-  + trying to get rid of Mythical Man of Month effect [#]_;
+  + the point of good documentation is getting rid of the
+    Mythical Man of Month effect [brooks-mythical-man-month];
     lowering threshold for new people
 
-.. [#] David Lorge Parnas and Paul C. Clements. A rational design process: 
-       How and why to fake it. IEEE TSE, SE-12(2):251--257, February 1986.
-
-.. [#] F. P. Brooks, JR., The Mythical Man-Month: Essays on Software 
-       Enginering. Reading, MA: Addison-Wesley 1975.
-
 UML
 ---
 
@@ -114,19 +111,17 @@
      code from the diagrams
    + generated diagrams are too detailed to be beneficial
    + basic architectural diagrams should be done before code anyway
+     (according to software design process models)
 
 Rational Rose
 
  - quite comprehensive UML design tool for different diagrams (class,
    sequence, state...) with direct manipulation interface
 
- - how rational rose links diagrams into code and documentation?
-
- - Automatically connecting documentation to code with rose; 
-   reverse engineering diagrams from existing source code 
+ - can reverse engingeer diagrams from existing source code
 
- - though, because we are coders, we would prefer UML language
-   over menus and dialogs when creating UML objects 
+ - though, because we are coders, we would prefer UML script 
+   language over menus and dialogs when creating UML objects 
 
    + we need a ref. of criticism of direct manipulation! 
    + though, directmanipulation is only relevant solution for
@@ -144,12 +139,13 @@
  - should describe somewhere why these are useles... 
 
 
-MetaPhor, hypertext in soft. devel? (http://metaphor.it.jyu.fi/
+MetaPhor, hypertext in soft. devel? [metaphor]
 
  - bi-directional linking of CASE-tool documents/objects (e.g. double 
    clicking an object opens more detailed diagram, backlink could
    be found from popup-menu... anyway, a lot of menus to select
-   objects for linking or already linked objects to show)
+   objects for linking or already linked objects to show) 
+   [lyytinen-kerola-metaphor]
 
  - MetaEdit+
 
@@ -157,10 +153,6 @@
    + could be used to create domain spesific languages, when generating
      code can really work
 
-   Kalle Lyytinen, Pekka Kerola. (1994). MetaPHOR Project: Final 
-   Report. Department of Computer Science and Information Systems. 
-   University of Jyvaskyla. <http://metaphor.it.jyu.fi/loppurap/>
-
 Javadoc
 -------
 
@@ -227,16 +219,11 @@
     hard to find?
 
  + hypertext disorientation problem still exists with javadoc
-
-   Edwards, D., & Hardman, L. (1989). Lost in Hyperspace: 
-   Cognitive Mapping and Navigation in a Hypertext Environment. 
-   In R. McAleese, & C. Green (Eds.), Hypertext: Theory into 
-   Practice (105-125), Oxford: Intellect Limited. 
-   (code in JYU-lib: "MK TIE HYPER")
-
+   [edward-hardman-lost-in-hyperspace]
 
 "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
@@ -391,15 +378,15 @@
 - Borges's "taxonomy" for animals;
   http://www.multicians.org/thvv/borges-animals.html
 
-- A Taxonomy of Link Types;
-  http://www.workpractice.com/trigg/thesis-chap4.html
+- A Taxonomy of Link Types:
   
   Thinking about linking... at first we do have UML->reST and 
   UML->javadoc links. Because of embedding diagrams implicitly
   into target documents we can see linking also as 
   bi-directional reST<->javadoc, reST<->reST, and javadoc<->javadoc.
 
-  Mapping our links to types defined by Trigg (Normal links)::
+  Mapping our links to types defined by Trigg {trigg-link-taxonomy]
+  (Normal links)::
 
     reST <-> reST  Alternate View