[Gzz-commits] manuscripts/UMLLink umllink.rst

[Tuomas J. Lukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Tuomas J. Lukka <address@hidden>        03/01/22 16:07:44

Modified files:
        UMLLink        : umllink.rst 

Log message:
        Organizing

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

Patches:
Index: manuscripts/UMLLink/umllink.rst
diff -u manuscripts/UMLLink/umllink.rst:1.33 
manuscripts/UMLLink/umllink.rst:1.34
--- manuscripts/UMLLink/umllink.rst:1.33        Wed Jan 22 13:17:15 2003
+++ manuscripts/UMLLink/umllink.rst     Wed Jan 22 16:07:44 2003
@@ -2,8 +2,8 @@
 A free software toolchain for bidirectional linking between UML diagrams and 
Javadoc
 
====================================================================================
 
-:Stamp: $Id: umllink.rst,v 1.33 2003/01/22 18:17:15 tjl Exp $
-:Last-Modified: $Date: 2003/01/22 18:17:15 $
+:Stamp: $Id: umllink.rst,v 1.34 2003/01/22 21:07:44 tjl Exp $
+:Last-Modified: $Date: 2003/01/22 21:07:44 $
 
 Issues
 ======
@@ -12,10 +12,33 @@
   OTOH, talking more about us makes it more personal but may make it
   also seem less relevant to others' efforts.
 
+    SUGGESTED RESOLUTION: "Setting of problem" should be about us:
+    describe exactly what docs **we** have. Everything else
+    should be more general, and we should point out that
+    this situation is probably not uncommon.
+
 - do we need critics against graphical coding with UML somewhere?
   This could be found at least in articles supporting 
   domain spesific languages (which may be used for graphical coding)
 
+    RESOLVED: Probably not: graphical languages have not taken
+    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,
+
+    PARTIAL RESOLUTION: 
+
+       - proprietarity
+       - versioning much worse
+       - users = programmers --> used to editing text and compiling
+       - lack of good, **extensible** tools
+
+- why even outdated but well simplified diagram
+  is better than too detailed, automaticly up-to dated 
+  and reverse engineered diagram.
+
+ 
 Introduction
 ============
 
@@ -143,22 +166,43 @@
 Setting of problem
 ==================
 
-Javadoc
+In our project, ..., 
+the software engineering documentation
+is divided into two classes:
 
- - fully generated documentation from development
-   project's java source code
+The two types of documentation are complementary.
 
- - easy to find a given class, easy to check methods
++----------------------------------------+----------------------------------------------+
+|       Design docs                      |           Javadoc                   
         |
++----------------------------------------+----------------------------------------------+
+|                                        |                                     
         |
+| - good overall picture.                |  - easy to find a given class,      
         |
+|                                        |    easy to check all methods        
         |
+|                                        |                                     
         |
+| - little detail,                       |  - detailed                         
         |
+|                                        |                                     
         |
+| - may be slightly outdated at          |  - methods and classes *always* up 
to        |
+|   any particular time.                 |    date (generated from source),    
         |
+|                                        |    doc comments also usually        
         |
+|                                        |                                     
         |
+| - hard to find explanations            |  - no overall picture of classes' 
roles      |
+|   for a particular class.              |                                     
         |
+|                                        |                                     
         |
+| - UML diagrams                         |                                     
         |
+|                                        |                                     
         |
+| - written and organized by humans      |                                     
         |
+|                                        |                                     
         |
++----------------------------------------+----------------------------------------------+
+
+Javadoc
+
+ - fully generated documentation from javadoc comments
+   of each class and method in the java source code
 
    + the javadoc output filestructure follows the
      hierarchical tree structure of java packages and classes
 
- - the location in class-tree is well shown everywhere in
-   javadoc, but the role of single class or package in
-   developing software remains unknown
-
-   + hard to get overall picture.
-   + hypertext disorientation problem still exists
+ + hypertext disorientation problem still exists
 
    Edwards, D., & Hardman, L. (1989). Lost in Hyperspace: 
    Cognitive Mapping and Navigation in a Hypertext Environment. 
@@ -166,11 +210,12 @@
    Practice (105-125), Oxford: Intellect Limited. 
    (code in JYU-lib: "MK TIE HYPER")
 
- - because doc is generated from source, the class, method, field
-   names and their inline documentation are always up-to-date(!!)
 
 Architectural docs with UML diagrams: 
 
+
+
+
  - diagrams are from human to human
 
    + we don't wan to generate diagrams from the code or generate
@@ -178,26 +223,18 @@
    + generated diagrams are too detailed to be beneficial
    + basic architectural diagrams should be done before code anyway
 
- - good overall picture. 
 
- - little detail, 
-
- - may be slightly outdated at any particular time. 
       
-   + why even outdated but well simplified diagram
-     is better than too detailed, automaticly up-to dated 
-     and reverse engineered diagram.
 
- - distinct from the javadoc, hard to find explanations
-   for a particular class.
 
-   + and if documentation is outdated some particular classes
+   + and if design documentation is outdated some particular classes
      maybe don't even exist anymore!
 
  - these cover the most relevant parts from the architecture 
    and the code
 
-The two types of documentation are complementary.
+ - Include PEGs: possibly not-yet accepted or not-yet implemented proposals 
+   for architectural changes.
 
 "Obvious" question: can we increase the overall value by
 interconnecting the two?