[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:06:11

Modified files:
        UMLLink        : article.rst 

Log message:
        rereorg

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

Patches:
Index: manuscripts/UMLLink/article.rst
diff -u manuscripts/UMLLink/article.rst:1.57 
manuscripts/UMLLink/article.rst:1.58
--- manuscripts/UMLLink/article.rst:1.57        Sat Feb 15 08:02:50 2003
+++ manuscripts/UMLLink/article.rst     Sat Feb 15 08:06:11 2003
@@ -9,7 +9,7 @@
 .. Alternative title: "Free Software toolchain for bidirectional 
    linking between UML diagrams and Javadoc"
 
-.. :Stamp: $Id: article.rst,v 1.57 2003/02/15 13:02:50 tjl Exp $
+.. :Stamp: $Id: article.rst,v 1.58 2003/02/15 13:06:11 tjl Exp $
 
 .. Points for HT people
    ====================
@@ -182,9 +182,18 @@
 ..  Javadoc has plenty of unhierarchical links, but they are not meaningful, 
     they don't give the documentation any structure.
 
-The role of documentation in Software Engineering
+In the following sections, we first discuss the role of documentation
+in software engineering, then bring the problem of the distinct 
+documentation bodies into focus and present our solution and
+its implementation. Finally, we discuss our practical use of the tool
+and conclude.
+
+Documentation in Software Engineering
 =================================================
 
+Software engineering process
+----------------------------
+
 In their article "A rational design process: how and why to fake it"
 [parnas-clements86rational]_ Parnas and Clements argue that rational
 software design process is not generally possible, but acceptable
@@ -273,6 +282,50 @@
 intercommunication within our group, we believe manually made human
 abstracted documentation serves our purposes best.
 
+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?
+
+
 The problem of two separate pieces of documentation
 ===================================================
 
@@ -361,50 +414,6 @@
 
 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?
-
 XXX Hypertext blaablaa something...
 -----------------------------------