[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 08:02:50

Modified files:
        UMLLink        : article.rst 

Log message:
        reorg

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

Patches:
Index: manuscripts/UMLLink/article.rst
diff -u manuscripts/UMLLink/article.rst:1.56 
manuscripts/UMLLink/article.rst:1.57
--- manuscripts/UMLLink/article.rst:1.56        Sat Feb 15 07:50:46 2003
+++ manuscripts/UMLLink/article.rst     Sat Feb 15 08:02:50 2003
@@ -9,7 +9,7 @@
 .. Alternative title: "Free Software toolchain for bidirectional 
    linking between UML diagrams and Javadoc"
 
-.. :Stamp: $Id: article.rst,v 1.56 2003/02/15 12:50:46 tjl Exp $
+.. :Stamp: $Id: article.rst,v 1.57 2003/02/15 13:02:50 tjl Exp $
 
 .. Points for HT people
    ====================
@@ -153,56 +153,20 @@
 source files contain interfaces and often embedded documentation
 giving details on how the interfaces should be used. Although
 these two parts of documentation are semantically dependent, linking
-them is tedious -- if even possible -- when they are authored using different
-software.
-
-The Unified Modeling Language (UML) is the standard way to visually
-describe software 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)
-[booch-jacobson-rumbaugh98uml-user-guide-onpage-12]_, but the current
-trend in research 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
-[harrison-barton-raghavachari00uml-to-java]_. 
-Another use of UML is in reverse engineering, where
-diagrams may be produced from the source code
-[pierce-tilley02connecting-documentation-rose]_.
-
-In this article we focus on the more conventional use of UML
-to plan and document software 
-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
-features at the right level of abstraction are preferred:
-
-   "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."
-   [booch-jacobson-rumbaugh98uml-user-guide-onpage-24]_
-
-.. (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)?
+them by hand is tedious and error-prone since they are authored using different
+software. 
 
 In this article, we present a navigational aid which connects the two
-distinct areas of documentation, and its fairly easy implementation
-which supplements the toolchain of other Free Software
-[fsf02categories]_ we use. The other documentation tools can already
+distinct areas of documentation, and its lightweight implementation
+on top of a Free Software
+[fsf02categories]_ toolchain.
+The other documentation tools can already
 generate web pages, and our new software injects the added linking to those
 HTML files. The software automatically generates the linking deduced from
 readily available UML diagram descriptions in our documentation. This
 means the software was deployable without further authoring.
 
-Earlier, concept-based navigation and map-based navigation have added 
+Earlier concept-based navigation and map-based navigation have added 
 horizontal links on top of hierarchical hypertext [brusilovsky02-mapnav]_. 
 The structure we discuss in this paper is similar as the diagram becomes a
 navigational node, but we don't rely on keywords or heuristics in link 
@@ -218,8 +182,8 @@
 ..  Javadoc has plenty of unhierarchical links, but they are not meaningful, 
     they don't give the documentation any structure.
 
-Background on software development
-==================================
+The role of documentation in Software Engineering
+=================================================
 
 In their article "A rational design process: how and why to fake it"
 [parnas-clements86rational]_ Parnas and Clements argue that rational
@@ -397,6 +361,47 @@
 
 The design for bi-directional navigation
 ========================================
+
+UML
+---
+
+The Unified Modeling Language (UML) is the standard way to visually
+describe software 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)
+[booch-jacobson-rumbaugh98uml-user-guide-onpage-12]_, but the current
+trend in research 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
+[harrison-barton-raghavachari00uml-to-java]_. 
+Another use of UML is in reverse engineering, where
+diagrams may be produced from the source code
+[pierce-tilley02connecting-documentation-rose]_.
+
+In this article we focus on the more conventional use of UML
+to plan and document software 
+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
+features at the right level of abstraction are preferred:
+
+   "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."
+   [booch-jacobson-rumbaugh98uml-user-guide-onpage-24]_
+
+.. (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)?
+
 
 .. some references to the screenshots here?