[Top][All Lists]
[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
======
- [Gzz-commits] manuscripts/UMLLink umllink.rst, (continued)
- [Gzz-commits] manuscripts/UMLLink umllink.rst, Tuomas J. Lukka, 2003/01/21
- [Gzz-commits] manuscripts/UMLLink umllink.rst, Asko Soukka, 2003/01/21
- [Gzz-commits] manuscripts/UMLLink umllink.rst, Tuomas J. Lukka, 2003/01/21
- [Gzz-commits] manuscripts/UMLLink umllink.rst, Tuomas J. Lukka, 2003/01/21
- [Gzz-commits] manuscripts/UMLLink umllink.rst, Tuomas J. Lukka, 2003/01/21
- [Gzz-commits] manuscripts/UMLLink umllink.rst, Asko Soukka, 2003/01/22
- [Gzz-commits] manuscripts/UMLLink umllink.rst, Tuomas J. Lukka, 2003/01/22
- [Gzz-commits] manuscripts/UMLLink umllink.rst, Tuomas J. Lukka, 2003/01/22
- [Gzz-commits] manuscripts/UMLLink umllink.rst, Tuomas J. Lukka, 2003/01/22
- [Gzz-commits] manuscripts/UMLLink umllink.rst, Tuomas J. Lukka, 2003/01/22
- [Gzz-commits] manuscripts/UMLLink umllink.rst,
Tuomas J. Lukka <=
- [Gzz-commits] manuscripts/UMLLink umllink.rst, Tuomas J. Lukka, 2003/01/23
- [Gzz-commits] manuscripts/UMLLink umllink.rst, Tuomas J. Lukka, 2003/01/23
- [Gzz-commits] manuscripts/UMLLink umllink.rst, Tuomas J. Lukka, 2003/01/23
- [Gzz-commits] manuscripts/UMLLink umllink.rst, Tuomas J. Lukka, 2003/01/23
- [Gzz-commits] manuscripts/UMLLink umllink.rst, Asko Soukka, 2003/01/24
- [Gzz-commits] manuscripts/UMLLink umllink.rst, Tuomas J. Lukka, 2003/01/26
- [Gzz-commits] manuscripts/UMLLink umllink.rst, Benja Fallenstein, 2003/01/28