[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 12:34:57

Modified files:
        UMLLink        : article.rst 

Log message:
        example

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

Patches:
Index: manuscripts/UMLLink/article.rst
diff -u manuscripts/UMLLink/article.rst:1.68 
manuscripts/UMLLink/article.rst:1.69
--- manuscripts/UMLLink/article.rst:1.68        Sat Feb 15 12:16:55 2003
+++ manuscripts/UMLLink/article.rst     Sat Feb 15 12:34:57 2003
@@ -9,7 +9,7 @@
 .. Alternative title: "Free Software toolchain for bidirectional 
    linking between UML diagrams and Javadoc"
 
-.. :Stamp: $Id: article.rst,v 1.68 2003/02/15 17:16:55 tjl Exp $
+.. :Stamp: $Id: article.rst,v 1.69 2003/02/15 17:34:57 tjl Exp $
 
 .. Points for HT people
    ====================
@@ -304,8 +304,9 @@
 UML Diagrams
 ------------
 
-The Unified Modeling Language (UML) is the standard way to visually
-describe software constructs in diagrams
+The Unified Modeling Language (UML) is the standard way to 
+visually
+describe software architectures and constructs in diagrams
 [booch-jacobson-rumbaugh98uml-user-guide]_. It was originally
 developed for descriptions on an abstract level (many constructs
 cannot be directly expressed in any programming language)
@@ -348,9 +349,9 @@
 The problem of two separate bodies of documentation
 ===================================================
 
-In our project, as probably in most projects that use the Java programming
+In our software engineering project[gzz]_, as probably in most projects that 
use the Java programming
 language [java-ref]_, the software development documentation is
-divided into two separate domains: the design documentation and
+divided into two major 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 or of the architecture or refactoring 
design). 
@@ -402,9 +403,19 @@
 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.
+ongoing work are hard to find. 
+
+For example, when referring to the Javadoc on how to use some API,
+one often comes across an interface which is of the type that
+one would like to obtain from somewhere, but unless someone
+has explicitly written the instructions into the doc comments,
+the Javadoc will only explain how the interface is used.
+What is exasperates this situation is the certainty 
+that in the architectural document, there surely is a diagram and a section
+which talks about the issue but finding them will take time.
+
+The distinct pieces (Javadoc and the
+design documentation) cannot seen as a whole. 
 
 The obvious question, then, is: can we increase the overall value by 
hyperlinking the 
 two distinct pieces of documentation?