[Gzz-commits] manuscripts/UMLLink short-paper.rst

[Asko Soukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Asko Soukka <address@hidden>    03/04/24 07:53:20

Modified files:
        UMLLink        : short-paper.rst 

Log message:
        thoughts

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/short-paper.rst.diff?tr1=1.2&tr2=1.3&r1=text&r2=text

Patches:
Index: manuscripts/UMLLink/short-paper.rst
diff -u manuscripts/UMLLink/short-paper.rst:1.2 
manuscripts/UMLLink/short-paper.rst:1.3
--- manuscripts/UMLLink/short-paper.rst:1.2     Tue Apr 22 10:57:40 2003
+++ manuscripts/UMLLink/short-paper.rst Thu Apr 24 07:53:20 2003
@@ -2,7 +2,7 @@
 Bridging Javadoc and design documentation via UML diagram image maps
 ====================================================================
 
-.. $Id: short-paper.rst,v 1.2 2003/04/22 14:57:40 humppake Exp $
+.. $Id: short-paper.rst,v 1.3 2003/04/24 11:53:20 humppake Exp $
 
 .. short paper == 2 pages, deadline the end of May
 
@@ -32,44 +32,67 @@
    Requirements traceability research
    - [humppake] couldn't find yet
 
+
+Sketching
+=========
+
 - short description about problem:
-  * how to make fragmented documentation connected with 
-    minimum additional work
+  * programming language specific tools generate 
+    well linked but distinct documentations from source code
+  * above all is human written abstraction to the system
+    as whole - the design documentation
+  * how to make these documentation fragments interconnected
+    with each other with minimum additional work
 
 - resolving:
-  * using programming language specific tools to generate 
-    documentations from source code level
-  * generate higher level design documentation
-  * connect these levels via UML diagrams drawn design documentation
+  * connecting distinct fragments together using design
+    documentation's UML diagrams
 
 - why UML
-  * UML as de facto standard for describing software architecture
-  * diagrams already exists, so why not use them
-  * probably not best for navigation, but still better than nothing
+  * UML is de facto standard for describing software architecture
+    - probably not best, but good enough and widely used
+  * diagrams must be drawn anyway, if they already exists, why not use them
+  * we do not claim that UML work as the best possible diagrams
+    for documentation navigation, but it's still much better than nothing
 
 - why UML-diagrams would work as menus
-  * human made abstraction of the system
+  * UMLs human made abstraction of the system containing
+    all the most relevant parts
   * don't link to everywhere, but to the most essential places
   * UMLs are already natural part of the design documentation
+    and thus, familiar to development grew reading documentation
+
+- how are UMLs embedded into documentation
+  * using lexical UML language
 
 - why lexical UML language:
   * no need for additional tools, when writing documentation
+  * describing is fast
+  * setting layout may be more 
+
+- why html
+  * platform and software independent documentation
+  * could be distributed in WWW, intranets etc... as it is
 
 - why Free Software
+  * good tools exist already for parts of toolchain
   * availibility
-  * openess (parts of docutils have been overwritten)
+  * openess (parts of docutils is overwritten - implementation
+    not possible / more difficult without open code)
   * ideology
   * cheapness
 
-- why html
-  * independent from possible CASE-tools
-  * could be distributed in WWW
-
 - pictures?
 
 - current implemention state
-  * gzz version ready
-  * separate navidoc version coming up
+  * created under gzz 
+  * separated as navidoc
+
+- does it really work
+  * WWW statistics from himalia, some comparison
+    between pages containing UML and pages that 
+    does not contain
+  * what does the previous prove?
 
 - future
   * fenfire