[Gzz-commits] manuscripts/UMLLink article.rst

[Asko Soukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Asko Soukka <address@hidden>    03/02/14 08:08:35

Modified files:
        UMLLink        : article.rst 

Log message:
        ennen kuin Tuukka hetii

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/article.rst.diff?tr1=1.21&tr2=1.22&r1=text&r2=text

Patches:
Index: manuscripts/UMLLink/article.rst
diff -u manuscripts/UMLLink/article.rst:1.21 
manuscripts/UMLLink/article.rst:1.22
--- manuscripts/UMLLink/article.rst:1.21        Thu Feb 13 14:14:10 2003
+++ manuscripts/UMLLink/article.rst     Fri Feb 14 08:08:35 2003
@@ -5,7 +5,7 @@
 .. Alternative title: "Free Software toolchain for bidirectional 
    linking between UML diagrams and Javadoc"
 
-.. :Stamp: $Id: article.rst,v 1.21 2003/02/13 19:14:10 humppake Exp $
+.. :Stamp: $Id: article.rst,v 1.22 2003/02/14 13:08:35 humppake Exp $
 
 .. Points for HT people
    ====================
@@ -54,7 +54,7 @@
           * Theories, models, architectures, standards, and frameworks 
     * Applications
           * Hypertext in workflow management systems
-          * Web-based hypermedia drama
+          * Web-based hypermedia dramarose
           * Hypermedia in fiction, scholarship, and technical writing
           * Hypermedia in education and training
           * Hypermedia and time: narratives and storyboarding
@@ -555,70 +555,133 @@
 documentation linking tool, which finally enabled the bi-directional
 linking between distinctdocumentations. In the following we discuss
 shortly, how we ended up to use this our own lexical UML language
-instead of using already existing free diagram drawing tool like Dia
-[larsson03dia]_, or CASE-tool like AgroUML [tigris03argouml]_.
-
-.. There exist also such Javadoc like tools, which generate some embedded
-   diagrams into documentation. Doxygen [heesch03doxygen]_ ,for example,
-   generates diagrams of class inheritance tree. Also proprietary
-   Rational Rose has could be
-
-Although, as discussed earlier, we wanted to use human created diagrams
-in our design documentation.
-
- - though, because we are coders, we would prefer UML description 
-   language over menus and dialogs when creating UML diagrams
-
-   + we need a ref. of criticism of direct manipulation!
-
-     - not necessarily improve performance, users must learn the meaning
-       of the graphical components, graphic presentation could be 
-       misleading, graphical presentation could take excessive screen display
-       space [Shneiderman-direct-manipulation, p. 64]
-
-       probably only the first argument of performance is relevant
-       anymore... though, creating the graphic presentation for problem
-       could lead to using metaphors and those are often
-       criticized (even by D. Norman :)
-      
-     - "The dark side of a direct manipulation interface is that
-       you have to directly manipulate everything. Instead of an
-       executive who gives high-level instructions, the user is 
-       reduced to an assembly line worker who must carry out the
-       same task over and over."
-       [gentner-nielsen-anti-mac, p.74]  
-
-       limits the precision of our actions to the precision
-       achieved  with eye-hand-mouse coordination (language and 
-       mathematics can be more precise)
-       [gentner-nielsen-anti-mac, p.74]  
-
-       direct manipulation requires the user to be involved in
-       every action, but sometimes the user may not know
-       what to do
-       [gentner-nielsen-anti-mac, p.74]  
+instead of using already existing free direct manipulation diagram
+drawing tools like Dia [larsson03dia]_, or CASE-tool like AgroUML
+[tigris03argouml]_.
+
+There exist also such Javadoc like tools, which generate some embedded
+diagrams into documentation. Doxygen [heesch03doxygen]_ ,for example,
+generates diagrams of class inheritance tree. Also proprietary
+Rational Rose could be used to reverse engineer UML diagrams and build
+up to date documentation (with support of Rational Soda) from source
+code [pierce-tilley02connecting-documentation-rose]_. 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.
+
+As we want to remove the barrier of drawing at least small diagrams
+within the documentation to make it more understandable, the drawing
+method should be easily integrated into current working
+customs. Because in small softaware development group programmers also
+write the documentation, the documentation tools shouldn't be gap to
+change the programming tool to document writing tools. Even better
+would be that the programming tool could be used as documentation
+tool. Lexical UML description for our UML drawing tool, of course, can
+be written with any text editor. At least for a programmer, who are
+used to describe objects lexically, describing also the UML diagrams
+could be even more efficient than using direct manipulation drawing
+tool.
 
        "It's as if we have thrown away a million years of 
        evolution, lost our facility with expressive language,
        and been reduced to pointing at objects in the immediate
-       environment. -- We have lost all the power of language, and
+       environment.-- --We have lost all the power of language, and
        can no longer talk about objects that are not immidiately
-       visible."    
-       [gentner-nielsen-anti-mac, p.74]  
+       visible." [gentner-nielsen96anti-mac]_ (pp74)
 
-     - summaring: direct manipulation could be easy, if there is
-       a natural graphic presentation for the problem. Even then 
-       it's not necesesserily the most efficient method. Also the
-       practical point of using the same writing tool foor coding and 
-       documenting.
-
-   + Rose's problem with direct manipulation: a lot of windows, 
-     menus, dialogies etc... to get direct manipulateable graphic
-     representation for everything
+The direct manipulation user interface do not necessarily improve
+performance: users must learn the meaning of the graphical components,
+graphic presentation could be misleading, graphical presentation could
+take excessive screen display space
+[shneiderman83direct-manipulation]_ (pp64). The direct manipulation
+interfaces could be also rather slow to use, since in a such interface
+user have to directly manipulate everything. Instead of an executive
+who gives high-level instructions, the user is reduced to an assembly
+line worker who must carry out the same task over and over
+[gentner-nielsen96anti-mac]_ (pp74). The UML langage has XXX different
+symbols and XXX different connections between them. It is a quite
+challanging for a direct manipulation interface to make all these
+alternatives as easily available as they could be typed within lexical
+description.
+
+Describing existing objects for diagram is easy done as lexical
+description, but the graphical placing of objects is a bit more
+complicated, although, not impossible.
+
+:: figure
+
+       bigpackage Example
+       class Interface "interface"
+         methods
+            void first()
+
+       class Derived "interface"
+         inherit Interface
+         methods
+            void second()
+
+       class Abstract "abstract"
+         methods
+            void third()
+           void fourth()
+
+       class Implementation
+         realize Derived
+         realize Abstract
+         assoc compos multi(1) - multi(*) role(part_of) Component
+
+       class Component
+       ------------------------------------------------------------------
+       Derived.c = (100, 100);
+         horizontally(50, derived_h, Interface, Derived, Abstract);
+         vertically(50, derived_v, Derived, Implementation); 
 
-   + though, directmanipulation is only relevant solution for
-     replacing already created object
+       Component.c = (300, 17);
+         horizontally(50, component_h, Component);
+ 
+       pad = 30;                           
+       Example.nw = Interface.nw + (-pad,pad);
+       Example.se = Component.se + (pad,-pad);
+
+.. UML:: umlink-example
+
+       bigpackage First
+       class Interface "interface"
+         methods
+            void first()
+
+       class Derived "interface"
+         inherit Interface
+         methods
+            void second()
+
+       class Abstract "abstract"
+         methods
+            void third()
+           void fourth()
+
+       class Implementation
+         realize Derived
+         realize Abstract
+         assoc compos multi(1) - multi(*) role(part_of) Component
+
+       class Component
+
+       ---
+
+       Derived.c = (100, 100);
+         horizontally(50, derived_h, Interface, Derived, Abstract);
+         vertically(50, derived_v, Derived, Implementation); 
 
+       Component.c = (300, 17);
+         horizontally(50, component_h, Component);
+ 
+       pad = 30;                           
+       First.nw = Interface.nw + (-pad,pad);
+       First.se = Component.se + (pad,-pad);
 
 Docutils
 --------