[Gzz-commits] manuscripts/UMLLink SCRATCH umllink.rst

[Asko Soukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Asko Soukka <address@hidden>    03/01/30 06:47:15

Modified files:
        UMLLink        : SCRATCH umllink.rst 

Log message:
        about dev process

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/SCRATCH.diff?tr1=1.11&tr2=1.12&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/umllink.rst.diff?tr1=1.51&tr2=1.52&r1=text&r2=text

Patches:
Index: manuscripts/UMLLink/SCRATCH
diff -u manuscripts/UMLLink/SCRATCH:1.11 manuscripts/UMLLink/SCRATCH:1.12
--- manuscripts/UMLLink/SCRATCH:1.11    Mon Jan 27 09:19:38 2003
+++ manuscripts/UMLLink/SCRATCH Thu Jan 30 06:47:15 2003
@@ -1,7 +1,20 @@
-:Stamp: $Id: SCRATCH,v 1.11 2003/01/27 14:19:38 humppake Exp $
+:Stamp: $Id: SCRATCH,v 1.12 2003/01/30 11:47:15 humppake Exp $
 
 trashbin
 --------
+
+  + the point of good and documentation is to reduce the
+    Mythical Man of Month effect ;
+    lowering threshold for new people; help intercommunication
+    within the group
+
+    - [p. 17] "In tasks that can be partitioned but which require
+      communication among subtasks, the effort of communication
+      must be added to the amount of work to be done."
+
+    - our group's working culture - flexible work times and and
+      decentralized working places - is especially vulnerable to 
+      intercommunication problems
 
    + and if design documentation is outdated some particular classes
      maybe don't even exist anymore!
Index: manuscripts/UMLLink/umllink.rst
diff -u manuscripts/UMLLink/umllink.rst:1.51 
manuscripts/UMLLink/umllink.rst:1.52
--- manuscripts/UMLLink/umllink.rst:1.51        Tue Jan 28 11:12:07 2003
+++ manuscripts/UMLLink/umllink.rst     Thu Jan 30 06:47:15 2003
@@ -2,7 +2,7 @@
 A free software toolchain for bidirectional linking between UML diagrams and 
Javadoc
 
====================================================================================
 
-:Stamp: $Id: umllink.rst,v 1.51 2003/01/28 16:12:07 benja Exp $
+:Stamp: $Id: umllink.rst,v 1.52 2003/01/30 11:47:15 humppake Exp $
 
 Issues
 ======
@@ -92,52 +92,88 @@
 Software development processes
 ------------------------------
 
-- our development process seems to be closing Boehm's spiral model
-  [boehm-spiral-model] of software development(, though our spiral is
-  endless and we have probably several of them running simultaneously)
-
-- architectural documents are important parts of design,
-  redesign and maintenance phases of the design process
-
-  + faking a rational design process
-    [parnas-clements-rational, pp.252-255]:
-
-    A) establish and document requirements
-    B) design and document the module structure
-    C) design and document the module interfaces
-    D) design and document the uses hierarchy
-    E) design and document the module internal structures
-    F) write programs
-    G) maintain (redesign and redevelopment, keeping documentation
-       up-to-date).
-
-  + creating UML diagrams should be natural part our of design
-    (pegboard) and documenting (architecture docs) processes
-
-  + as a small group we have too small budget for
-    large tools like Rational Rose (also ideological reasons
-    to use open source, though open code is always extensible)
-     
-  + the point of good and documentation is to reduce the
-    Mythical Man of Month effect [brooks-mythical-man-month];
-    lowering threshold for new people; help intercommunication
-    within the group
-
-    - [p. 16] "Men and months are interchangeable commodities only
-      when a task can be partitioned among many workers with no
-      communication."
-    - [p. 17] "In tasks that can be partitioned but which require
-      communication among subtasks, the effort of communication
-      must be added to the amount of work to be done."
-    - [p. 18] "The added burden of communication is made up of two
-      parts, training and intercommunication. Each worker must be trained
-      in the technology, the goasl of the effort, the overall strategy, and
-      the plan of work." "Intercommunication is worse."
-
-    - our group's working culture - flexible work times and and
-      decentralized working places - is especially vulnerable to 
-      intercommunication problems
-
+In their article "A rational design process: how and why to fake it" [#]_
+Parnas and Clements argue that rational software design process is not
+generally possible, but acceptable results could be achieved by faking
+"the ideal process". Their ideal software design process contains the 
+following steps{#]_: 
+
+  A) establish and document requirements
+  B) design and document the module structure
+  C) design and document the module interfaces
+  D) design and document the uses hierarchy
+  E) design and document the module internal structures
+  F) write programs
+  G) maintain (redesign and redevelopment, keeping documentation
+     up-to-date).
+
+.. [#] parnas-clements-rational
+
+.. [#] parnas-clements-rational, pp.252-255 
+
+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 could be used
+as reference manuals throughout the building of the software [#]_. In a
+theory in an open software 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 open software projects could be geographically widely 
+decentralized. This results the Mythical Man Month effect[#]_: adding a 
+new member into software design process could rather delay than speed up 
+the project:
+
+  "Men and months are interchangeable commodities only when a task can be 
+  partitioned among many workers with no communication."[#]_
+
+  "The added burden of communication is made up of two
+  parts, training and intercommunication. Each worker must be trained
+  in the technology, the goal of the effort, the overall strategy, and
+  the plan of work.-- --Intercommunication is worse."[#]_
+
+.. [#] brooks-mythical-man-month
+
+.. [#] brooks-mythical-man-month p.16
+
+.. [#] brooks-mythical-man-month p.18
+
+Eventually, the greater is the amount of programmers or higher turnover within
+them, the more important is to have a good documentation. When new programmers
+join the project they shouldn't have to depend completely on the old staff for
+they information. An up-to-date and rational set of documents available for
+them could ameliorate the Mythical Man Month effect[#]_.
+
+.. [#] parnas-clements-rational p.255
+
+Because our group is doing experimental research, we need a flexible
+model for software development process. From the classical software
+decelopment process models, our one reminds most Boehm's spiral model
+of software development and enhancement [#]_. The spiral model
+is a cyclic and repeative model, where every cycle has the following
+phases [#]_:
+
+ * determining objectives, alternatives, constraints
+ * evaluating alternatives, identifying and resolving risks
+ * developing, verifying
+ * planning next phase
+
+.. [#] boehm-spiral-model
+
+.. [#] boehm-spiral-model p.64
+
+The nature of our software development process affects also strongly to
+our documentation needs. As we proceed by prototyping and enhancing our
+software step by step, also our documentation should be updated in every
+cycle. Because the detailed implementation is in continual change, we prefer
+to weight our documentation to more constant and general architectural
+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 general documentation rapidly changing details
+would be irrelevant and confusing. Since currently the main purpose for our
+documentation is help intercommunication within our group, we believe manually
+made human abstracted documentation serving purposes best.
+  
 Javadoc
 -------
 
@@ -268,11 +304,9 @@
 
 Dia  (drawing, generating code templates)
 
- - Dia [#]_ a free software (licensed under GPL) diagram creating program 
-   with direct manipulation user interface.
+ - Dia [#]_ is a free software (licensed under GPL) diagram 
+   creating program with direct manipulation user interface.
  - more a drawing than a design tool
- - could be used instead of metapost, but
-   direct manipulation problem again
 
 .. [#] http://www.lysator.liu.se/~alla/dia/
 
@@ -325,6 +359,15 @@
  - Include PEGs: possibly not-yet accepted or not-yet implemented proposals 
    for architectural changes.
 
+
+  + creating UML diagrams should be natural part our of design
+    (pegboard) and documenting (architecture docs) processes
+
+  + as a small group we have too small budget for
+    large tools like Rational Rose (also ideological reasons
+    to use open source, though open code is always extensible)
+     
+
 Javadoc, on the other hand, is 
 
  - fully generated documentation from javadoc comments
@@ -630,6 +673,10 @@
 
      - placement: currently metapost; looking at ways to make 
        interactively editable.
+
+- Dia could be used instead of metapost, but
+  direct manipulation problem again
+
 
 Practical use
 =============