[Gzz-commits] manuscripts ./gzigzag.bib UMLLink/article.rst

[Asko Soukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Asko Soukka <address@hidden>    03/02/13 08:27:59

Modified files:
        .              : gzigzag.bib 
        UMLLink        : article.rst 

Log message:
        refs/edit

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/gzigzag.bib.diff?tr1=1.26&tr2=1.27&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/article.rst.diff?tr1=1.14&tr2=1.15&r1=text&r2=text

Patches:
Index: manuscripts/UMLLink/article.rst
diff -u manuscripts/UMLLink/article.rst:1.14 
manuscripts/UMLLink/article.rst:1.15
--- manuscripts/UMLLink/article.rst:1.14        Thu Feb 13 04:40:34 2003
+++ manuscripts/UMLLink/article.rst     Thu Feb 13 08:27:58 2003
@@ -5,7 +5,7 @@
 .. Alternative title: "Free Software toolchain for bidirectional 
    linking between UML diagrams and Javadoc"
 
-.. :Stamp: $Id: article.rst,v 1.14 2003/02/13 09:40:34 humppake Exp $
+.. :Stamp: $Id: article.rst,v 1.15 2003/02/13 13:27:58 humppake Exp $
 
 .. Points for HT people
    ====================
@@ -141,7 +141,7 @@
 [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]_, but current trend is to
+[booch-jacobson-rumbaugh98uml-user-guide]_(pp12), but current trend 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
@@ -149,9 +149,6 @@
 produced from the source code
 [pierce-tilley02connecting-documentation-rose]_.
 
-.. uml user guide p.XXX
-.. uml user guide p.12
-
 Against this trend, we still use UML only to plan and document our software 
 architecture on general level. UML functions as a common language for 
 communication within our software development team, and in this purpose we
@@ -163,9 +160,7 @@
    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]_ 
-
-.. from uml user guide p.24
+   [booch-jacobson-rumbaugh98uml-user-guide]_(pp24) 
 
 .. (could other stakeholders be identified and described to some
    extent somewhere? it might be interesting to think also towards
@@ -196,6 +191,95 @@
 
 ..  XXX move last chapter away from Introduction?
 
+Background
+==========
+
+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
+results could be achieved by faking "the ideal process". Their ideal
+software design process contains the following steps
+[parnas-clements86rational]_(pp252--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).
+
+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 [brooks75mythical-man-month]_. In theory in an open 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
+Month effect [brooks75mythical-man-month]_(pp16): 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."
+  [brooks75mythical-man-month]_(pp18)
+
+  "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."
+  [brooks75mythical-man-month]_(pp18)
+
+Eventually, the greater is the amount of programmers or higher the
+turnover within them, the more important it is to have a good
+documentation.  When new programmers join the project they shouldn't
+have to depend completely on the old staff for their information. An
+up-to-date and rational set of documents available for them could
+ameliorate the Mythical Man Month effect
+[parnas-clements86rational]_(pp255).
+
+Because our group is doing experimental research, 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,
+and every cycle has the following phases [boehm88spiral-model]_(pp64):
+
+ * 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
+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
+splitted into even smaller cycles and the analysis of the design
+objects continues throughout the design process. [beck99xp]_ The Spiral Model 
emphasizes documenting the changes before implamenting them 
[boehm88spiral-model]_, the Extreme programming don't say much about progr
+       
+.. [#] beck99xp
+
+The nature of our software development process affects also 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. Because the detailed implementation is in continual change, we prefer
+to emphasis the 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 to help intercommunication within our group, we believe 
manually
+made human abstracted documentation serves our purposes best.
+
+
 Implementation
 ==============
 
@@ -254,7 +338,7 @@
    generates diagrams of class inheritance tree. Also proprietary
    Rational Rose has could be
 
-Though,as discussed earlier, we wanted to use human created diagrams
+Although, as discussed earlier, we wanted to use human created diagrams
 in our design documentation.
 
  - though, because we are coders, we would prefer UML description 
Index: manuscripts/gzigzag.bib
diff -u manuscripts/gzigzag.bib:1.26 manuscripts/gzigzag.bib:1.27
--- manuscripts/gzigzag.bib:1.26        Thu Feb 13 07:02:27 2003
+++ manuscripts/gzigzag.bib     Thu Feb 13 08:27:58 2003
@@ -3028,7 +3028,7 @@
     publisher = {Addison-Wesley Object Technology Series. Addison-Wesley}
 }
 
address@hidden boehm-spiral-model,
address@hidden boehm88spiral-model,
     author = {Boehm, B.},
     title = {A spiral model for software development and enhancement},
     year = {1988},
@@ -3038,7 +3038,7 @@
     pages = {61--72},
 }
 
address@hidden parnas-clements-rational,
address@hidden parnas-clements86rational,
     author = {David Lorge Parnas and Paul C. Clements},
     title = {A rational design process: How and why to fake it.},
     year = {1986},
@@ -3048,17 +3048,7 @@
     pages = {251--257},
 }
 
address@hidden parnas-clements-rational,
-    author = {David Lorge Parnas and Paul C. Clements},
-    title = {A rational design process: How and why to fake it.},
-    year = {1986},
-    journal = {IEEE Transactions on Software Engineering},
-    volume = {12},
-    issue = {2},
-    pages = {251--257},
-}
-
address@hidden brooks-mythical-man-month,
address@hidden brooks75mythical-man-month,
     author = {F. P. Brooks, JR.},
     title = {Essays on Software Enginering.},
     year = {1975},