[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gzz-commits] manuscripts/UMLLink article.rst
From: |
Tuukka Hastrup |
Subject: |
[Gzz-commits] manuscripts/UMLLink article.rst |
Date: |
Wed, 12 Feb 2003 04:59:11 -0500 |
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
==============
- [Gzz-commits] manuscripts/UMLLink article.rst, Tuukka Hastrup, 2003/02/10
- [Gzz-commits] manuscripts/UMLLink article.rst, Tuukka Hastrup, 2003/02/10
- [Gzz-commits] manuscripts/UMLLink article.rst, Tuukka Hastrup, 2003/02/11
- [Gzz-commits] manuscripts/UMLLink article.rst, Tuukka Hastrup, 2003/02/11
- [Gzz-commits] manuscripts/UMLLink article.rst, Tuukka Hastrup, 2003/02/12
- [Gzz-commits] manuscripts/UMLLink article.rst,
Tuukka Hastrup <=
- [Gzz-commits] manuscripts/UMLLink article.rst, Tuukka Hastrup, 2003/02/12
- [Gzz-commits] manuscripts/UMLLink article.rst, Tuukka Hastrup, 2003/02/12
- [Gzz-commits] manuscripts/UMLLink article.rst, Asko Soukka, 2003/02/12
- [Gzz-commits] manuscripts/UMLLink article.rst, Asko Soukka, 2003/02/13
- [Gzz-commits] manuscripts/UMLLink article.rst, Asko Soukka, 2003/02/13
- [Gzz-commits] manuscripts/UMLLink article.rst, Asko Soukka, 2003/02/13
- [Gzz-commits] manuscripts/UMLLink article.rst, Asko Soukka, 2003/02/13
- [Gzz-commits] manuscripts/UMLLink article.rst, Asko Soukka, 2003/02/13
- [Gzz-commits] manuscripts/UMLLink article.rst, Asko Soukka, 2003/02/13
- [Gzz-commits] manuscripts/UMLLink article.rst, Asko Soukka, 2003/02/14