gzz-commits
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Gzz-commits] manuscripts/UMLLink umllink.rst


From: Tuomas J. Lukka
Subject: [Gzz-commits] manuscripts/UMLLink umllink.rst
Date: Thu, 23 Jan 2003 02:41:14 -0500

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Tuomas J. Lukka <address@hidden>        03/01/23 02:41:14

Modified files:
        UMLLink        : umllink.rst 

Log message:
        structuring

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

Patches:
Index: manuscripts/UMLLink/umllink.rst
diff -u manuscripts/UMLLink/umllink.rst:1.35 
manuscripts/UMLLink/umllink.rst:1.36
--- manuscripts/UMLLink/umllink.rst:1.35        Wed Jan 22 16:11:28 2003
+++ manuscripts/UMLLink/umllink.rst     Thu Jan 23 02:41:13 2003
@@ -2,8 +2,8 @@
 A free software toolchain for bidirectional linking between UML diagrams and 
Javadoc
 
====================================================================================
 
-:Stamp: $Id: umllink.rst,v 1.35 2003/01/22 21:11:28 tjl Exp $
-:Last-Modified: $Date: 2003/01/22 21:11:28 $
+:Stamp: $Id: umllink.rst,v 1.36 2003/01/23 07:41:13 tjl Exp $
+:Last-Modified: $Date: 2003/01/23 07:41:13 $
 
 Issues
 ======
@@ -166,22 +166,13 @@
 Setting of problem
 ==================
 
-In our project, ..., 
-the software engineering documentation
-is divided into two classes:
-
-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
-
-Architectural docs with UML diagrams: 
-
-
-
+In our project, as probably in most projects that use Java, 
+the software engineering (not user!) documentation is divided into two classes:
+design documentation and Javadoc.
+
+The design documents cover the most important architectural features
+and are written either before coding (for design) or after (for exposition
+of the architecture).
 
  - diagrams are from human to human
 
@@ -190,21 +181,29 @@
    + generated diagrams are too detailed to be beneficial
    + basic architectural diagrams should be done before code anyway
 
-
-      
-
-
    + 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
 
  - Include PEGs: possibly not-yet accepted or not-yet implemented proposals 
    for architectural changes.
 
+Javadoc, on the other hand, is 
 
-The two types of documentation are complementary, as demonstrated in the 
following table..
+ - 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 two types of documentation are complementary, as demonstrated in the 
following table:
 
 
+----------------------------------------+----------------------------------------------+
 |       Design docs                      |           Javadoc                   
         |
@@ -227,13 +226,14 @@
 | - written and organized by humans      |                                     
         |
 |                                        |                                     
         |
 
+----------------------------------------+----------------------------------------------+
-"Obvious" question: can we increase the overall value by
-interconnecting the two?
 
-Architectural docs easily left in the dark reaches of the filesystem,
-not used as often as javadocs.
+Problems with the docs:
 
- + hypertext disorientation problem still exists
+ +  Architectural docs easily left in the dark reaches of the filesystem,
+    not used as often as javadocs. - refs about documents left unused because
+    hard to find?
+
+ + hypertext disorientation problem still exists with javadoc
 
    Edwards, D., & Hardman, L. (1989). Lost in Hyperspace: 
    Cognitive Mapping and Navigation in a Hypertext Environment. 
@@ -241,6 +241,9 @@
    Practice (105-125), Oxford: Intellect Limited. 
    (code in JYU-lib: "MK TIE HYPER")
 
+
+"Obvious" question: can we increase the overall value by
+interconnecting the two?
 
 Design
 ======




reply via email to

[Prev in Thread] Current Thread [Next in Thread]