[Gzz-commits] manuscripts/UMLLink article.rst

[Tuukka Hastrup]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Tuukka Hastrup <address@hidden> 03/02/12 04:59:09

Modified files:
        UMLLink        : article.rst 

Log message:
        next version of Introduction

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

Patches:
Index: manuscripts/UMLLink/article.rst
diff -u manuscripts/UMLLink/article.rst:1.6 manuscripts/UMLLink/article.rst:1.7
--- manuscripts/UMLLink/article.rst:1.6 Wed Feb 12 02:51:41 2003
+++ manuscripts/UMLLink/article.rst     Wed Feb 12 04:59:09 2003
@@ -4,7 +4,7 @@
 
 Alternative title: "Bridging Javadoc to design documentation via UML diagrams"?
 
-:Stamp: $Id: article.rst,v 1.6 2003/02/12 07:51:41 tuukkah Exp $
+:Stamp: $Id: article.rst,v 1.7 2003/02/12 09:59:09 tuukkah Exp $
 
 Points for HT people
 ====================
@@ -107,7 +107,7 @@
 * UML diagrams: distinct context for Java classes and packages and relevant 
   architectural documentation; spatial menu; also node (XXX multi-ended nexus
   links)
-       * generated by our UML tool from our UML diagram description language
+      * generated by our UML tool from our UML diagram description language
 
 * Cross-reference by Javadoc: cheap cross-link
 * Cross-link from javadoc comments: simple hyperlink
@@ -115,10 +115,69 @@
   (poorly implemented as WWW)
 
 * Links in UML diagrams: context navigation links
-       * generated by our UML link tool without any extra information
+    * generated by our UML link tool without any extra information
 
 * (XXX Free Software vs. Open Source vs. Open Software vs. Open Project...)
 
+
+Introduction
+============
+
+Software projects manage a large base of evolving documentation, which is 
+inter-related on many levels. Design documentation gives architectural views 
+on more general level, while the program code source files give all the minute 
+details on how the computer should act and contain embedded documentation for 
+human-readability. Although these two parts of documentation are 
+semantically dependent, in praftice they are often linked scarcely -- if at 
+all.
+
+The Unified Modeling Language (UML) is the standard way to visually describe
+software constructs in diagrams. It was originally developed for descriptions 
+on an abstract level (many constructs cannot be directly expressed in 
+any programming language), but current trend is to use it also on the concrete 
+level, as to fully unify the architectural documentation and program code: the 
+program code might be generated from highly detailed diagrams, or exact 
+diagrams be produced from the source code.
+
+Against this trend, we still use UML only to plan and document our software 
+architecture on general level. UML functions as a common language for 
+communication within our software development team, and in this purpose we
+prefer better abstracted and more comprehensible
+human-drawn diagrams to exact illustrations matching source code to 
+every detail: 
+
+    "You draw diagrams to visualize a system from different
+    perspectives, so a diagram is a projection into a system.
+    For all but the most trivial systems, a diagram represents an elided
+    view of the elements that make up a system." [#]_
+
+:   (could other stakeholders be identified and described to some extent
+    somewhere? it might be interesting to think also towards users/customers,
+    who in some methods (ways of using XP) control use cases themselves)
+
+:   UML is easier to read than write. Also, non-programmers often don't have
+    the insight needed to directly take part in designing (even in use cases)?
+
+.. [#] booch-jacobson-rumbaugh-uml-user-guide, p.24
+
+
+In this article, we present a navigational tool which connects the two distinct
+areas of documentation, and the fairly simple tool implementation which 
+supplements the toolchain of other Free Software [] we use. The other 
+documentation tools can already generate web pages, and the tool injects the 
+added linking to those HTML files. The tool automatically generates the 
+linking deduced from readily available UML diagram descriptions in our 
+documentation. This means the tool is deployable without further authoring. 
+
+It turns out that in addition to working as multi-ended links, the diagrams 
+each generate a new navigational context within the target nodes. We found
+this useful because the Javadoc tool, which we use for program code 
+documentation, does not promote un-hierarchical coherence.
+
+: Javadoc has plenty of unhierarchical links, but they are not meaningful, 
+  they don't give the documentation any structure.
+
+: XXX move last chapter away from Introduction?
 
 Implementation
 ==============