[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: |
Wed, 22 Jan 2003 16:07:44 -0500 |
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?
- Re: [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, 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 <=
- [Gzz-commits] manuscripts/UMLLink umllink.rst, Tuomas J. Lukka, 2003/01/22
- [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, 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