[Gzz-commits] manuscripts/UMLLink article.rst

[Tuomas J. Lukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Tuomas J. Lukka <address@hidden>        03/02/15 09:13:05

Modified files:
        UMLLink        : article.rst 

Log message:
        Fixing mentions

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

Patches:
Index: manuscripts/UMLLink/article.rst
diff -u manuscripts/UMLLink/article.rst:1.63 
manuscripts/UMLLink/article.rst:1.64
--- manuscripts/UMLLink/article.rst:1.63        Sat Feb 15 08:58:42 2003
+++ manuscripts/UMLLink/article.rst     Sat Feb 15 09:13:05 2003
@@ -9,7 +9,7 @@
 .. Alternative title: "Free Software toolchain for bidirectional 
    linking between UML diagrams and Javadoc"
 
-.. :Stamp: $Id: article.rst,v 1.63 2003/02/15 13:58:42 tjl Exp $
+.. :Stamp: $Id: article.rst,v 1.64 2003/02/15 14:13:05 tjl Exp $
 
 .. Points for HT people
    ====================
@@ -168,7 +168,8 @@
 
 In this article, we present a navigational aid for software engineering 
documentation.
 Based on using UML diagrams as multi-ended links, our tool connects two
-distinct areas of software engineering documentation: architectural documents 
and javadoc.
+distinct areas of software engineering documentation: 
+the general architectural documents and the detailed method-level javadoc 
documentation.
 
 .. XXX This means the software was deployable without further authoring.
 
@@ -267,7 +268,7 @@
 require a more formal process for changes, as in the Spiral Model.
 On the outer edges of the system, new research is taking place and should
 not be hampered by process or documentation beyond the immediate
-needs of the group members.
+needs of the group members involved in the development of that particular part.
 
 Because of this, it is important for us that the documentation system
 is powerful and flexible: the core parts must have a comprehensive,
@@ -311,7 +312,7 @@
 architecture on a general level. 
 UML can function as a common language for 
 communication within a software development team, and for this purpose 
-human-drawn (non-autogenerated) diagrams show the semantically meaningful
+human-drawn (non-autogenerated) diagrams that show the semantically meaningful
 features at the right level of abstraction are preferred:
 
    "You draw diagrams to visualize a system from different
@@ -336,17 +337,17 @@
 The problem of two separate pieces of documentation
 ===================================================
 
-In our project, as probably in most projects that use Java programming
+In our project, as probably in most projects that use the Java programming
 language [java-ref]_, the software development documentation is
-divided into two classes: the design documentation and
+divided into two separate domains: the design documentation and
 Javadoc [friendly95javadoc]_. The design documents cover the most
 important architectural features and are written either before coding
-(for design) or after (for exposition of the architecture). Javadoc,
+(for design) or after (for exposition or of the architecture or refactoring 
design). 
+Javadoc,
 on the other hand, is a detailed and fully generated documentation from
 javadoc comments of each class and method in the Java source code.
-
 The two types of documentation are complementary, as demonstrated 
-in the following table:
+in Table [ref-documentations]:
 
 .. figure:: table
    :environment: table
@@ -376,44 +377,35 @@
    | humans                       | rigidly by package structure     |
    +------------------------------+----------------------------------+
 
-Because Javadoc is fully generated, it is always up to date. Our
-design documentation, though, is updated manually. Of course, it
-should be updated regularly during every design cycle, but in practise
-that won't always happen. From our point of view it is still
-ridiculous even talk about generating the design documentation; the
-design should always be made by human, and if the design documentation
-is for human reading, it should be also human made. What we could do,
-is lower the treshold of writing the design documentation and
-explaining the design using UML diagrams.
-
-For detailed documentation we have decided to use Javadoc, since even
-though it's not Free Software it's still usable for free and quite
-easy to use. Also the likeness of documentation with most of the other
-Java based projects is a significant issue. A more difficult issue is
-to select tools for writing the design documentation and drawing
-diagrams into it. The solution should be cheap, and as a Free Software
-project we would prefer other Free Software. Also the solution should
-fit well to our current working customs.
+..  From our point of view it is still
+    ridiculous even talk about generating the design documentation; the
+    design should always be made by human, and if the design documentation
+    is for human reading, it should be also human made. 
+
+..  For detailed documentation we have decided to use Javadoc, since even
+    though it's not Free Software it's still usable for free and quite
+    easy to use. Also the likeness of documentation with most of the other
+    Java based projects is a significant issue. 
 
-In addition to the tool selection problem we have to problem of two
-distinct pieces of documentation: the human written design
-documentation and the automatically generated detailed Javadoc
-documentation. During coding, the Javadoc documentation is often
-necessary, but the design documentation could be easily left in the
+During coding, the Javadoc documentation is often
+necessary, but the design documentation is easily left in the
 dark reaches of the filesystem. It could be argued that the reason for
 design documents being left unused is that relevant parts linked to
 ongoing work are hard to find. The distinct pieces (Javadoc and the
 design documentation) cannot seen as a whole. Therefore we should make
 them work better as a whole.
 
-"Obvious" question: can we increase the overall value by interconnecting the 
+The obvious question, then, is: can we increase the overall value by 
hyperlinking the 
 two distinct pieces of documentation? 
 
 When looking at a design document, jumping to the Javadocs to get the
 details would be useful, and when looking at a Javadoc, it would be
-useful to be able to see if any design documents refer to that class.
-We believe that the architecture document will be read more, after
-it's easily reachable from relevant parts of Javadoc. This is the
+most useful to be able to see if any design documents discuss that class
+or package.
+We believe that the architecture document would be read more if 
+made easily reachable from relevant parts of Javadoc. 
+
+This is the
 starting point for the Free Software toolchain we developed in this
 article: a toolchain for bidirectional linking between design
 documentation and Javadoc, using UML diagrams as multi-ended nexus
@@ -760,6 +752,22 @@
 
 Docutils
 --------
+
+Because Javadoc is generated from special doc comments in the
+source code, it is almost always up to date. 
+The design documentation, though, is updated manually. Of course, it
+should be updated regularly during every design cycle, but in practise
+that won't always happen. 
+To avoid out-of-date design documentation,
+the treshold of writing the design documentation and
+explaining the design using UML diagrams should be as low as possible.
+
+A more difficult issue is
+to select tools for writing the design documentation and drawing
+diagrams into it. The solution should be cheap, and as a Free Software
+project we would prefer other Free Software. Also the solution should
+fit well to our current working customs.
+
 
 As a natural continuum for UML tool we started to use reStructuredText
 (reST) plaintext syntax with Docutils parsering system