[Gzz-commits] manuscripts/UMLLink article.rst

[Benja Fallenstein]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Benja Fallenstein <address@hidden>      03/02/15 05:13:24

Modified files:
        UMLLink        : article.rst 

Log message:
        language

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

Patches:
Index: manuscripts/UMLLink/article.rst
diff -u manuscripts/UMLLink/article.rst:1.43 
manuscripts/UMLLink/article.rst:1.44
--- manuscripts/UMLLink/article.rst:1.43        Sat Feb 15 04:57:44 2003
+++ manuscripts/UMLLink/article.rst     Sat Feb 15 05:13:23 2003
@@ -9,7 +9,7 @@
 .. Alternative title: "Free Software toolchain for bidirectional 
    linking between UML diagrams and Javadoc"
 
-.. :Stamp: $Id: article.rst,v 1.43 2003/02/15 09:57:44 benja Exp $
+.. :Stamp: $Id: article.rst,v 1.44 2003/02/15 10:13:23 benja Exp $
 
 .. Points for HT people
    ====================
@@ -137,7 +137,9 @@
 ========
 
 We describe automatic linking of design documentation to javadoc
-through UML diagrams embedded in both, acting as nexus links.
+through UML diagrams embedded in both, acting as multi-target nexus links.
+Our simple implementation as a Free Software toolchain is in daily use
+in our project.
 
 XXX !!!
 
@@ -191,7 +193,7 @@
 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
-generate web pages, and the new software injects the added linking to those
+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.
@@ -211,7 +213,7 @@
 
 The current implementation is a part of and in use at our Free
 Software project [gzz]_, where it generates the publicly web-browsable
-hypertext [gzz_doc_himalia]_ of project's documentation, as a part of
+hypertext [gzz_doc_himalia]_ of the project's documentation, as a part of
 the toolchain.
 
 ..  Javadoc has plenty of unhierarchical links, but they are not meaningful, 
@@ -227,28 +229,28 @@
 software design process contains the following steps
 [parnas-clements86rational-onpage-252-255]_:
 
-  - establish and document requirements
-  - design and document the module structure
-  - design and document the module interfaces
-  - design and document the uses hierarchy
-  - design and document the module internal structures
-  - write programs
-  - maintain (redesign and redevelopment, keeping documentation
-    up to date).
-
-It should be clear that documentation plays major role in the
-ideal software design process. Steps listed above should produce
-documentation, which records requirements or design decisions and
+- establish and document requirements
+- design and document the module structure
+- design and document the module interfaces
+- design and document the uses hierarchy
+- design and document the module internal structures
+- write programs
+- maintain (redesign and redevelopment, keeping documentation
+  up to date).
+
+It should be clear that documentation plays a major role in the
+ideal software design process. The steps listed above should produce
+documentation which records requirements or design decisions and
 could be used as reference manuals throughout the building of the
 software [brooks75mythical-man-month]_. In theory, in a Free
-Software [fsf02categories]_ project new programmers are always free to
-participate independently. In practice a new programmer could need a
-lot of mentoring by other group members, before one could be
-productive for the project. Sometimes sufficient mentoring could not
-even be possible, because members of such a projects could be
-geographically widely scattered. This results in the Mythical Man
+Software project, new programmers are always free to
+participate independently. In practice a new programmer may need a
+lot of mentoring by other group members before being able to contribute
+productively to the project. Sometimes sufficient mentoring isn't
+even possible, because members of a project are
+scattered geographically. This results in the Mythical Man
 Month effect [brooks75mythical-man-month-onpage-16]_: adding a new member
-into software design process could rather delay than speed up the
+into the software design process delays than speeds up the
 project.
 
   "Men and months are interchangeable commodities only when a task can be 
@@ -261,40 +263,39 @@
   the plan of work.-- --Intercommunication is worse."
   [brooks75mythical-man-month-onpage-18]_
 
-Eventually, the greater is the amount of programmers or higher the
-turnover within them, the more important it is to have a good
+Eventually, the greater the amount of programmers or the higher the
+turnover rate, the more important it is to have good
 documentation.  When new programmers join the project they shouldn't
-have to depend completely on the old staff for their information. An
+have to depend completely on the old staff for finding their way around. An
 up to date and rational set of documents available for them could
 ameliorate the Mythical Man Month effect
 [parnas-clements86rational-onpage-255]_.
 
 Because our group is doing experimental research with a rather small
 group and as an open Free Software project, we need a flexible model
-for software development process. From the classical software
-development process models, ours reminds most of Boehm's Spiral Model
-of software development and enhancement [boehm88spiral-model]_. From
-the modern models our development process is influenced by Extreme
-Programming [beck99xp]_. The Spiral Model is cyclic and repetitive,
+for software development. From the classical software
+development process models, ours mostly resembles Boehm's Spiral Model
+of software development and enhancement [boehm88spiral-model]_. Among
+the modern models, Extreme Programming [beck99xp]_ is a strong influence
+on our development process. The Spiral Model is cyclic and repetitive,
 and every cycle has the following phases [boehm88spiral-model-onpage-64]_:
 
- * analysis: determining objectives, alternatives, constraints
- * design: evaluating alternatives, identifying and resolving risks
- * implementation: developing,
- * test: verifying
- * planning next phase...
+* analysis: determining objectives, alternatives, constraints
+* design: evaluating alternatives, identifying and resolving risks
+* implementation: developing,
+* test: verifying
+* planning next phase...
 
-When comparing the Extreme Programming to the spiral model, the
+When comparing Extreme Programming to the spiral model,
 Extreme Programming blends all phases of a single Spiral Model's
 cycle, a little at a time, throughout the entire software development
-process.a single development cycle is even shorter than in the spriral
-model. Though, the development process in Extreme Programming is
+process. The development process in Extreme Programming is
 splitted into even smaller cycles and the analysis of the design
-objects continues throughout the design process. [beck99xp]_ The
-Spiral Model emphasizes a lot documenting the changes before
-implementing them [boehm88spiral-model]_. The Extreme Programming
-don't speak out much about documentation, but relies on unit tests
-keeping the software coherent and working [beck99xp]_.
+objects continues throughout the design process [beck99xp]_. The
+Spiral Model emphasizes documenting changes before
+implementing them [boehm88spiral-model]_. Extreme Programming
+doesn't emphasize documentation very much, relying on unit tests
+instead for keeping the software coherent and working [beck99xp]_.
 
 The nature of our software development process affects strongly our
 documentation needs. As we proceed by prototyping and enhancing our