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

[Asko Soukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Asko Soukka <address@hidden>    03/01/30 11:19:51

Modified files:
        UMLLink        : SCRATCH umllink.rst 

Log message:
        background

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

Patches:
Index: manuscripts/UMLLink/SCRATCH
diff -u manuscripts/UMLLink/SCRATCH:1.12 manuscripts/UMLLink/SCRATCH:1.13
--- manuscripts/UMLLink/SCRATCH:1.12    Thu Jan 30 06:47:15 2003
+++ manuscripts/UMLLink/SCRATCH Thu Jan 30 11:19:51 2003
@@ -1,7 +1,15 @@
-:Stamp: $Id: SCRATCH,v 1.12 2003/01/30 11:47:15 humppake Exp $
+:Stamp: $Id: SCRATCH,v 1.13 2003/01/30 16:19:51 humppake Exp $
 
 trashbin
 --------
+
+ - diagrams are from human to human
+
+   + we don't wan to generate diagrams from the code or generate
+     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)
 
   + the point of good and documentation is to reduce the
     Mythical Man of Month effect ;
Index: manuscripts/UMLLink/umllink.rst
diff -u manuscripts/UMLLink/umllink.rst:1.52 
manuscripts/UMLLink/umllink.rst:1.53
--- manuscripts/UMLLink/umllink.rst:1.52        Thu Jan 30 06:47:15 2003
+++ manuscripts/UMLLink/umllink.rst     Thu Jan 30 11:19:51 2003
@@ -2,7 +2,7 @@
 A free software toolchain for bidirectional linking between UML diagrams and 
Javadoc
 
====================================================================================
 
-:Stamp: $Id: umllink.rst,v 1.52 2003/01/30 11:47:15 humppake Exp $
+:Stamp: $Id: umllink.rst,v 1.53 2003/01/30 16:19:51 humppake Exp $
 
 Issues
 ======
@@ -171,178 +171,82 @@
 generated from the current source for those members, who are working with
 particular details. Though, in general documentation rapidly changing details
 would be irrelevant and confusing. Since currently the main purpose for our
-documentation is help intercommunication within our group, we believe manually
-made human abstracted documentation serving purposes best.
+documentation is to help intercommunication within our group, we believe 
manually
+made human abstracted documentation serving our purposes best.
   
 Javadoc
 -------
 
-Javadoc  [#]_ is a hypertext documentation tool developed by Sun 
+**Javadoc** [#]_ is a hypertext documentation tool developed by Sun 
 Microsystems and delivered with Sun's Java distribution packages [#]_. 
-Javadoc generates detailed and well crosslinked documentation analyzing
-classes and including also comments from java source packages. Besides
-crosslinking, Javadoc creates indexes and archical trees as navigational
-aids for finding individual classes.
+Javadoc generates detailed and well crosslinked hypertext documentation
+analyzing class hierarchies and including documentation comments from 
+java source packages. Besides crosslinking, Javadoc creates indexes and 
+hierarchical trees as navigational aids for locating individual classes.
 
 .. [#] http://java.sun.com/j2se/javadoc/
 
 .. [#] Java is a trademark of Sun Microsystems
 
 Sun's distribution of Javadoc tools is proprietary, but there exists
-also free software (licensed unde GPL) alternatives like doc++ [#]_, 
-which can create documentation also from sources of other languages 
-(e.g. C++).
+also free software (licensed unde GPL) alternatives like doc++ [#]_.
+Doc++ is designed to create hypertext documentation also from sourcefile
+of other languages (e.g. C, C++, perl).
 
 .. [#] http://docpp.sourceforge.net/
 
 UML
 ---
 
- - diagrams are from human to human
+**Rational Rose** [#]_ is quite honored UML design tool. It provides a 
+direct manipulation interface for drawing different kinds of UML diagrams
+into it's data model, which is also supported by other products of Rational
+Software Corporations Rational product family. In addition of drawing
+diagrams from scratch, it allows reverse engineering diagrams from
+code [#]_.
+
+Rational Rose could be used with **Rational Soda** [#]_ for creating more
+general architecture documentation. Soda is WYSIWYG (What You See Is What
+You Get) documentation writing tool which allows including diagrams and 
+documentation data from Rational Rose's data model within the written 
+documentation. The both, Rational Rose and Rational Soda, are proprietary
+software and quite expensive for use of small research groups. Problems of 
+direct manipulation and WYSIWYG interfaces are discussed later.
 
-   + we don't wan to generate diagrams from the code or generate
-     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)
+.. [#] http://www.rational.com/products/rose/
 
-Rational Rose
-
- - part of rational devtool suite
-
- - quite comprehensive UML design tool for different diagrams (class,
-   sequence, state...) with direct manipulation interface
- - can reverse engingeer diagrams from existing source code
-
- - co-operating with Rational Soda, Soda is WYSIWYG
-   [pierce-tilley02connecting-documentation-rose]
-
- - How should we discuss WYSIWYG, WYSIAYG/WYSIATI for reST &c? Someone will
-   surely ask about that,
-
-    PARTIAL RESOLUTION: 
-
-       - proprietarity (really?)
-       - versioning much worse 
-          (changes in rtf could probably be compared?)
-       - users = programmers --> used to editing text and compiling,
-          it's the most practical to use the same editor as for coding
-       - lack of good, **extensible** tools
-
-  
-   [gentner-nielsen-anti-mac, p.75] collects arguments/argues
-   generally against WYSIWYG.
- 
-    - a document has a rich semantic structure that is poorly
-      captured by its appearance on a sceen or printed page
-    - other text representations, such as SGML, distinct the semantic
-      structure and rules for converting the text and semantics into
-      printablepage
-    - WYSIWYG assumes there is only one useful representation of the
-      information: that of the final reports
-    - WYSIWYG assumes people want paper-style reports (and we already
-      live within information flood)
-    - blind users exists
-
-    - Rational Soda is WYSIWYG, maybe this could be discussed under
-      it
-
- - 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!
-
-     - 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]  
-
-       "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
-       can no longer talk about objects that are not immidiately
-       visible."    
-       [gentner-nielsen-anti-mac, p.74]  
-
-     - 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
-
-   + though, directmanipulation is only relevant solution for
-     replacing already created object
-
- - proprietary
+.. [#] pierce-tilley02connecting-documentation-rose
 
-Dia  (drawing, generating code templates)
+.. [#] http://www.rational.com/products/soda/
 
- - Dia [#]_ is a free software (licensed under GPL) diagram 
-   creating program with direct manipulation user interface.
- - more a drawing than a design tool
+**Dia** [#]_ is a free software (licensed under GPL) alternative for diagram
+drawing with direct manipulation user interface. Dia is still more just a
+drawing than design tool, but it can export diagrams in several formats
+and it has a plugin interface for new drawing object sets.
 
 .. [#] http://www.lysator.liu.se/~alla/dia/
 
-Doxygen
-
- - Doxygen [#]_ is an another Javadoc-like documentation tool, which
-   generates hypertext documentation from source code of good variety
-   of different languges. An intresting feature in Doxygen is that
-   it generates and embeds UML diagrams representing software's 
-   class and inheritance hierarchies into class documentation. Also
-   the currently viewed class is higlighted in diagrams. Doxygen
-   also creates shrinkable treeview for class hierarchy.
-
- - can generate useless diagrams from the code class hierarchy
- - should describe somewhere why these are useles... 
- - uses proprietary GraphViz tool to create diagrams
+**Doxygen** [#]_ is an another Javadoc-like documentation tool, which generates
+hypertext documentation from source code of good variety of different languges.
+An intresting feature in Doxygen is that it can also generates and embed
+UML diagrams representing software's class and inheritance hierarchies into 
+class documentation. Also the focused class is higlighted in diagrams on its
+documentation pages. Another enhancement for javadoc in Doxygen is that
+it creates dynamic shrinkable treeview for class hierarchy.
 
 .. [#] http://www.doxygen.org/
 
-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) 
-   [lyytinen-kerola-metaphor]
-
- - MetaEdit+
-
-   + meta CASE tool; could be made to generate code from the diagrams 
-   + could be used to create domain spesific languages, when generating
-     code can really work
+**MetaPhor** [#]_ Project group in University of Jyväskylä have
+looked for ways of using hypertext in CASE tools[#_]. Results of its research
+have been used in **MetaEdit+**[#]_ meta CASE tool developed by MetaCase 
+Consulting. MetaEdit+ provides bi-directional linking between all its objects
+and interface for reaching linking contexts from diagrams' objects. [ XXX This
+should be checked, but metaphor.it.jyu.fi seems to be down :( ]
+
+.. [#] metaphor
+.. [#] lyytinen-kerola-metaphor
+.. [#] http://www.metacase.com/
 
-(We found no open source alternativa to our own development, which 
-combines all the good parts we need from previous tools without
-reformin dramatically our workin culture.)
 
 Setting of problem
 ==================
@@ -397,6 +301,8 @@
 |                                        |                                     
         |
 
+----------------------------------------+----------------------------------------------+
 
+
+
 Problems with the docs:
 
  +  Architectural docs easily left in the dark reaches of the filesystem,
@@ -424,6 +330,7 @@
    devices would be those that are spatially based." 
    [edward-hardman-lost-in-hyperspace, p.123] 
 
+
 "Obvious" question: can we increase the overall value by
 interconnecting the two? 
 
@@ -627,6 +534,10 @@
 Implementation
 ==============
 
+(We found no open source alternativa to our own development, which 
+combines all the good parts we need from previous tools without
+reformin dramatically our workin culture.)
+
 + HTML/WWW browsers don't support bi-directional links
 
 Goals:
@@ -653,6 +564,95 @@
 - "ASCII layout" (our UML-language is an exception, which is discussed later)
 
 Why UML-language
+
+ - Doxygen can generate useless diagrams from the code class hierarchy 
+   should describe somewhere why these are useles... 
+   uses proprietary GraphViz tool to create diagrams
+
+
+ - How should we discuss WYSIWYG, WYSIAYG/WYSIATI for reST &c? Someone will
+   surely ask about that,
+
+    PARTIAL RESOLUTION: 
+
+       - proprietarity (really?)
+       - versioning much worse 
+          (changes in rtf could probably be compared?)
+       - users = programmers --> used to editing text and compiling,
+          it's the most practical to use the same editor as for coding
+       - lack of good, **extensible** tools
+
+  
+   [gentner-nielsen-anti-mac, p.75] collects arguments/argues
+   generally against WYSIWYG.
+ 
+    - a document has a rich semantic structure that is poorly
+      captured by its appearance on a sceen or printed page
+    - other text representations, such as SGML, distinct the semantic
+      structure and rules for converting the text and semantics into
+      printablepage
+    - WYSIWYG assumes there is only one useful representation of the
+      information: that of the final reports
+    - WYSIWYG assumes people want paper-style reports (and we already
+      live within information flood)
+    - blind users exists
+
+    - Rational Soda is WYSIWYG, maybe this could be discussed under
+      it
+
+ - 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!
+
+     - 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]  
+
+       "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
+       can no longer talk about objects that are not immidiately
+       visible."    
+       [gentner-nielsen-anti-mac, p.74]  
+
+     - 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
+
+   + though, directmanipulation is only relevant solution for
+     replacing already created object
+
 
 - not strictly necessary; could have used another editor