[Gzz-commits] manuscripts/UMLLink umllink.rst Uml_inclusion.jpg

[Asko Soukka]

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

Modified files:
        UMLLink        : umllink.rst 
Added files:
        UMLLink        : Uml_inclusion.jpg 

Log message:
        quick edit (bad english, fuzzy structure ;)

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/Uml_inclusion.jpg?rev=1.1
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/umllink.rst.diff?tr1=1.4&tr2=1.5&r1=text&r2=text

Patches:
Index: manuscripts/UMLLink/umllink.rst
diff -u manuscripts/UMLLink/umllink.rst:1.4 manuscripts/UMLLink/umllink.rst:1.5
--- manuscripts/UMLLink/umllink.rst:1.4 Wed Jan 15 08:59:59 2003
+++ manuscripts/UMLLink/umllink.rst     Thu Jan 16 10:57:09 2003
@@ -1,60 +1,86 @@
+====================================================================================
 A free software toolchain for bidirectional linking between UML diagrams and 
Javadoc
 
====================================================================================
 
-IEEE
-ACM
-
-tarvitaan:
-- suoramanipulointikritiikkiä (nopea kaavioiden luonti kirjoittamisen ohessa 
tjsp)
-- nimi käyttöliittymän "olet tässä" korostukseen
-- "Kaavio on valikko."
+Recommended sources for references: IEEE, ACM
 
 Previous work
 =============
 
 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?
+ - though, because we are coders, we would prefer UML language
+   over menus and dialogs when creating UML objects 
+   + we need critic for direct manipulation! 
+   + though, direcmanipulation is only relevant solution for
+     replacing already created objects
+
 Dia (drawing, generating code templates)
-doc++ (osaa generoida hyödyttömiä kaavioita koodista)
- -miksi hyödyttömiä?
 
-Doc++ - autogen not-so-useful diagrams
+ - more a drawing than design tool
+ - could be used instead of metapost, but
+   direct manipulation problem again
 
-Design
-======
+doc++
 
-Ensin lukijan näkökulma.
+ - can generate useless diagrams from the code class hierarchy
+ - should describe somewhere why these are useles... 
 
-Asekl 0 Aluksi erillinen arkkitehtuuridokumentaatio ja javadoc (ei linkkejä).
-Askel 1 linkit arkkitehtuuridokumentaation UML-kaavioista javadockiin
- ei riitä, koska blaa
-Askel 2 UML-kaavioiden implisiittinen sijoitus javadociin, ei hyväratkaisu, 
koska 
-Askel 3 paluulinkit, jolloin UML-diagrammeista tule navigaatiovalikkoja 
(paluulinkit osa UML-kaaviota, valikkometafora, kuvan pysyvyys ja korostus)
+Doc++ - autogen not-so-useful diagrams
 
-Kirjoittajan näkökulma
+MetaEdit (from JYU)
+ - meta CASE tool; could be made to create code from the diagrams 
+ - used for domain spesific languages
 
-seurataan RST:n filosofiaa (sisennys blokeille, robusti, "luonnollinen", ASCII,
-rakenne ja piirto erikseen)
- - alhainen kynnys tehdä kaavio
- - diagrammit samassa RST-sorsassa, pieni kynnys (jos osaa kielen)
- - vain tieto tarkasta luokasta, ts. yksi eksplisiittinen linkki
- - paluulinkit implisiittisiä
+This page lists a lot of UML tools:
+http://plg.uwaterloo.ca/~migod/uml.html
 
+Design
+======
 
-Lähtökohtina:
-- erillinen arkkitehtuuridokumentaatio (ihmiseltä ihmiselle), _olennaiset_
-  arkitehtoniset piirteet (esimerkiksi rakenteet, kutsusekvenssi)
-- tarkka koodista generoitu javadoc (tai muu) (kertoo yksityiskohdat, ei 
yleiskuvaa)
+Documentation's reader's point of view
+---------------------------------------
 
-- halutaan piirtää kaaviot itse (UML-kirja)
-- nähdään luokan dokumentaatiosta helposti, missä siitä on mainittu jossan 
(viittaukset)
+Our developing steps:
 
-- kieli, ei suoramanipulaatiota
+ - step 0; distinct architecture documentation with UML diagrams 
+   and javadoc generated from the sourcecode
+ - step 1; links from architecture documentation's UML-diagrams into
+   relevant javadoc class documentations
+   + when only following dummy link into some part of 
+     javadoc tree, we would lost the class' context in the architecture
+     documentation we started
+ - step 2; embedding UML-diagrams into javadoc, linking also them
+   + though, this is not yet enough, because we want to know
+      where classes are referred in architecture documentation
+   + "focus+context menu"-metaphor for diagrams needs that we can
+     "step back" from class documentation back to architecture
+     documentation
+ - step 3; backlinks to the architecture documentation
+   + all this (UML and rerer backlinks)  drawn into diagram for consistency
+
+Documentation's developer's point of view
+-----------------------------------------
+
+reST's filosophy
+
+ - indentation for blocks
+ - robust for erros
+ - "natural" to write
+ - "ASCII layout" (our UML-language is an exception)
+
+Why UML-language
+
+ - minimum cap to make a diagram (well, at first have to learn our UML-script)
+ - diagrams in the same reST source than the architecture document
+ - only explicit link from diagram object to the class it represents is
+   obligatory, all other are implicit
 
 Goals:
     
-    - päämääränä ei ole koodin generointi kaavioista (kuten esimerkiksi 
metaedit/RationalRose) eikä
-      kaavioiden generointi koodista (RationalRose)
-
     - light-weight
 
     - using existing free software tools
@@ -73,8 +99,25 @@
 
     - placement: currently metapost; looking at ways to make interactively
       editable.
-      + elementin luonti kielellä
-      + graafinen sijoittelu suoramanipulaatiolla
+      + elements are easy to create by script language
+      + graphical placing could need an GUI
+
+- distinct architecture documentation, where 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
+  + these cover the most relevant parts from the architecture and the code
+- creating UML diagrams to natural part of our design (pegboard) and
+  documenting (architecture docs) process
+  + how our development process diffs from "the common way"?
+  + too small budget for large tookillls like Rational Rose
+- minimize the cap of drawing a even small diagram to make
+  document more clear
+- link diagrams' objects to code documentation, which 
+  they represent
+- implicitly embed diagrams into relevant code documentation, and
+  backlink code documentation to design documentation
+- make diagrams work as context+focusing menus to the code documentation
 
 
 UML diagram of how architectural documents, UML diagrams and javadoc pages 
work.
@@ -95,13 +138,18 @@
 Practical use
 =============
 
-- n luokkaa, n kaaviota, n arkkitehtuurikaaviota ja toimii
-- vapaa softa => tärkeää, että helppo päästä sisään, tarve
-  hyvälle dokumentaatiolle (tjsp)
+- n classes, n diagrams, n pages architecture documentation, and works
+- we develop open software => good documentation is needed for
+  lowering threshold for new people
 
 Conclusion
 ==========
 
-- sijoittelun helpottaminen (ei kuitenkaan automaatista sijoittelua)
-- diagrammin virheiden raportointi vaatii kehitystä
-- on mahdollista, että vaihdamme metapostia (virheiden kryptisyys, kääntämisen 
hitaus) (oma UML-kieli säilyy samana)
\ No newline at end of file
+...
+
+- easier placing (but not automatic)
+- metapost's erros are fuzzy, when using scripting language for
+  drawing diagrams, we need clearer errors
+- it's possible that we change metapost for something else
+  + getting rid of problem with error messages and slow compiling process
+  + we can still continue using our UML language