[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 12:16:55

Modified files:
        UMLLink        : article.rst 

Log message:
        Comment out lots of stuff that isn't the point in that section -- do we 
want to make it somewhere else?

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

Patches:
Index: manuscripts/UMLLink/article.rst
diff -u manuscripts/UMLLink/article.rst:1.67 
manuscripts/UMLLink/article.rst:1.68
--- manuscripts/UMLLink/article.rst:1.67        Sat Feb 15 10:00:21 2003
+++ manuscripts/UMLLink/article.rst     Sat Feb 15 12:16:55 2003
@@ -1,6 +1,6 @@
-============================================================
-Bridging Javadoc and design documentation via UML image maps
-============================================================
+====================================================================
+Bridging Javadoc and design documentation via UML diagram image maps
+====================================================================
 
 
 .. "Imagemapped UML diagrams as link nodes"
@@ -9,7 +9,7 @@
 .. Alternative title: "Free Software toolchain for bidirectional 
    linking between UML diagrams and Javadoc"
 
-.. :Stamp: $Id: article.rst,v 1.67 2003/02/15 15:00:21 humppake Exp $
+.. :Stamp: $Id: article.rst,v 1.68 2003/02/15 17:16:55 tjl Exp $
 
 .. Points for HT people
    ====================
@@ -182,7 +182,7 @@
 its implementation. Finally, we discuss our practical use of the tool
 and conclude.
 
-Documentation in Software Engineering
+Background: Documentation in Software Engineering
 =================================================
 
 Software engineering process
@@ -205,16 +205,25 @@
   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
+ideal software design process, and that there are several different
+types of documentation at different levels of abstraction. 
+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 project, new programmers are always free to
-participate independently. In practice a new programmer may need a
+could be referenced throughout the building of the
+software [brooks75mythical-man-month]_. 
+
+..  In theory, in a Free
+    Software project, new programmers are always free to
+    participate independently. 
+
+..  Sometimes sufficient mentoring isn't
+    even possible, because members of a project are
+    scattered geographically. 
+
+A programmer joining a project 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
+productively to the project. 
+This results in the Mythical Man
 Month effect [brooks75mythical-man-month-onpage-16]_: adding a new member
 into the software design process delays rather than speeds up the
 project.
@@ -236,45 +245,47 @@
 up to date and rational set of documents available for them could
 ameliorate the Mythical Man Month effect
 [parnas-clements86rational-onpage-255]_.
+Improving the learning curve of new programmers may have significant effects.
 
-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
-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...
-
-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. The development process in Extreme Programming is
-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]_.
-
-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 involved in the development of that particular part.
-
-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.
+
+..  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
+    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...
+
+    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. The development process in Extreme Programming is
+    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]_.
+
+    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 involved in the development of that particular 
part.
+
+    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
@@ -290,8 +301,8 @@
     intercommunication within our group, we believe manually made human
     abstracted documentation serves our purposes best.
 
-UML
----
+UML Diagrams
+------------
 
 The Unified Modeling Language (UML) is the standard way to visually
 describe software constructs in diagrams
@@ -334,7 +345,7 @@
 .. some references to the screenshots here?
 
 
-The problem of two separate pieces of documentation
+The problem of two separate bodies of documentation
 ===================================================
 
 In our project, as probably in most projects that use the Java programming
@@ -411,8 +422,9 @@
 documentation and Javadoc, using UML diagrams as multi-ended nexus
 links.
 
-The design for bi-directional navigation
-========================================
+
+A design for multi-directional navigation through UML diagram imagemaps
+=======================================================================
 
 Usability considerations
 ------------------------
@@ -514,7 +526,7 @@
 
 .. at least here we should also refer to the screenshots
 
-Before reaching the current state, our documentation evolved through
+Before reaching its current state, our documentation evolved through
 several distinct steps, which will be viewed first from the reader's
 and then from the developer's point of view.