[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:58:42

Modified files:
        UMLLink        : article.rst 

Log message:
        Devel ideas

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

Patches:
Index: manuscripts/UMLLink/article.rst
diff -u manuscripts/UMLLink/article.rst:1.62 
manuscripts/UMLLink/article.rst:1.63
--- manuscripts/UMLLink/article.rst:1.62        Sat Feb 15 08:47:03 2003
+++ manuscripts/UMLLink/article.rst     Sat Feb 15 08:58:42 2003
@@ -9,7 +9,7 @@
 .. Alternative title: "Free Software toolchain for bidirectional 
    linking between UML diagrams and Javadoc"
 
-.. :Stamp: $Id: article.rst,v 1.62 2003/02/15 13:47:03 tjl Exp $
+.. :Stamp: $Id: article.rst,v 1.63 2003/02/15 13:58:42 tjl Exp $
 
 .. Points for HT people
    ====================
@@ -141,8 +141,9 @@
     Our simple implementation as a Free Software toolchain is in daily use
     in our project.
 
-In this article, we present a navigational aid for software engineering 
documentation.
-Based on using UML diagrams as multi-ended links, the tool connects two
+We present a navigational aid for software engineering documentation.
+Based on using UML diagrams as multi-ended links, we hypertexturally
+connect two
 distinct areas of software engineering documentation: architectural documents 
and javadoc.
 
 and its lightweight implementation
@@ -166,7 +167,7 @@
 software. 
 
 In this article, we present a navigational aid for software engineering 
documentation.
-Based on using UML diagrams as multi-ended links, the tool connects two
+Based on using UML diagrams as multi-ended links, our tool connects two
 distinct areas of software engineering documentation: architectural documents 
and javadoc.
 
 .. XXX This means the software was deployable without further authoring.
@@ -214,7 +215,7 @@
 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 the software design process delays than speeds up the
+into the software design process delays rather than speeds up the
 project.
 
   "Men and months are interchangeable commodities only when a task can be 
@@ -227,7 +228,7 @@
   the plan of work.--- ---Intercommunication is worse."
   [brooks75mythical-man-month-onpage-18]_
 
-Eventually, the greater the amount of programmers or the higher the
+Obviously, 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 finding their way around. An
@@ -235,8 +236,8 @@
 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
+Because our group is doing experimental research with a relatively small
+group as an open Free Software project, we need a flexible model
 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
@@ -254,25 +255,39 @@
 Extreme Programming blends all phases of a single Spiral Model's
 cycle, a little at a time, throughout the entire software development
 process. The development process in Extreme Programming is
-splitted into even smaller cycles and the analysis of the design
+split into smaller cycles and the analysis of the design
 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
-software step by step, also our documentation should be updated in
-every cycle. Athough, the detailed implementation is in continual
-change, and we prefer to emphasis the more constant and general design
-documentation. Of course, more detailed up to date documentation could
-be generated from the current source for those members who are working
-with particular details. Though, in more general design documentation
-rapidly changing details would be irrelevant and confusing. Since
-currently the main purpose for our documentation is to help
-intercommunication within our group, we believe manually made human
-abstracted documentation serves our purposes best.
+In our development effort, different parts of the system have
+different needs: the core parts of the system are frozen and
+require a more formal process for changes, as in the Spiral Model.
+On the outer edges of the system, new research is taking place and should
+not be hampered by process or documentation beyond the immediate
+needs of the group members.
+
+Because of this, it is important for us that the documentation system
+is powerful and flexible: the core parts must have a comprehensive,
+easily navigable documentation but the documentation for the "edge"
+must be easy to write and maintain. 
+Thus, our documentation system should support both.
+
+
+..  The nature of our software development process affects strongly our
+    documentation needs. As we proceed by prototyping and enhancing our
+    software step by step, our documentation should also be updated in
+    every cycle. Athough, the detailed implementation is in continual
+    change, and we prefer to emphasis the more constant and general design
+    documentation. Of course, more detailed up to date documentation could
+    be generated from the current source for those members who are working
+    with particular details. Though, in more general design documentation
+    rapidly changing details would be irrelevant and confusing. Since
+    currently the main purpose for our documentation is to help
+    intercommunication within our group, we believe manually made human
+    abstracted documentation serves our purposes best.
 
 UML
 ---