[Gzz-commits] manuscripts/UMLLink umllink.rst

[Tuukka Hastrup]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Tuukka Hastrup <address@hidden> 03/02/11 08:52:45

Modified files:
        UMLLink        : umllink.rst 

Log message:
        rewordings trying to ensure understanding within Introduction and 
Background

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

Patches:
Index: manuscripts/UMLLink/umllink.rst
diff -u manuscripts/UMLLink/umllink.rst:1.61 
manuscripts/UMLLink/umllink.rst:1.62
--- manuscripts/UMLLink/umllink.rst:1.61        Tue Feb 11 07:35:08 2003
+++ manuscripts/UMLLink/umllink.rst     Tue Feb 11 08:52:44 2003
@@ -2,7 +2,7 @@
 A free software toolchain for bidirectional linking between UML diagrams and 
Javadoc
 
====================================================================================
 
-:Stamp: $Id: umllink.rst,v 1.61 2003/02/11 12:35:08 tuukkah Exp $
+:Stamp: $Id: umllink.rst,v 1.62 2003/02/11 13:52:44 tuukkah Exp $
 
 2nd round todo:
 ===============
@@ -101,12 +101,12 @@
 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
-theory in an open software project new programmers are always free to 
+theory in an open 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 
+because members of such a projects could be geographically widely 
+scattered. This results in the Mythical Man Month effect [#]_: adding a 
 new member into software design process could rather delay than speed up 
 the project:
 
@@ -126,19 +126,20 @@
 
 .. [#] 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
+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
-they information. An up-to-date and rational set of documents available for
+their 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
-development process models, our one reminds most Boehm's spiral model
+development process models, ours reminds most of Boehm's spiral model
 of software development and enhancement [#]_. The spiral model
-is a cyclic and repeative model, where every cycle has the following
+is cyclic and repetitive, and every cycle has the following
 phases [#]_:
 
  * determining objectives, alternatives, constraints
@@ -155,27 +156,28 @@
 
 .. [#] beck99xp
 
-The nature of our software development process affects also strongly to
+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 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
+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 serving our purposes best.
+made human abstracted documentation serves our purposes best.
   
 Javadoc
 -------
 
 **Javadoc** [#]_ is a hypertext documentation tool developed by Sun 
-Microsystems and delivered with Sun's Java distribution packages [#]_. 
-Javadoc generates detailed and well crosslinked hypertext documentation
-analyzing class hierarchies and including documentation comments from 
-java source packages. Besides crosslinking, Javadoc creates indexes and 
-hierarchical trees as navigational aids for locating individual classes.
+Microsystems and delivered with Sun's Java Development Kit [#]_. 
+Javadoc generates detailed and massively crosslinked hypertext documentation
+after analyzing class hierarchies and references, and includes documentation 
+comments from 
+java source code. Besides crosslinking, Javadoc creates alphabetical indexes 
+and hierarchical trees to aid navigation into individual classes.
 
 ``XXX Little more about Javadoc's history...``
 
@@ -184,10 +186,10 @@
 .. [#] Java is a trademark of Sun Microsystems XXX Friendly, L. had 
        a Java reference
 
-Sun's distribution of Javadoc tools is proprietary, but there exists
-also free software (licensed unde GPL) alternatives like doc++ [#]_.
-Doc++ is designed to create hypertext documentation also from sourcefile
-of other languages (e.g. C, C++, perl).
+Sun's distribution of Javadoc tools is proprietary, but alternatives such as
+doc++ [#]_ exist as free software (licensed under GPL).
+Doc++ is designed to create hypertext documentation from other languages 
+(e.g. C, C++, perl), in addition to Java.
 
 .. [#] http://docpp.sourceforge.net/
 
@@ -196,16 +198,16 @@
 
 **Rational Rose** [#]_ is quite honored UML design tool. It provides a 
 direct manipulation interface for drawing different kinds of UML diagrams
-into it's data model, which is also supported by other products of Rational
-Software Corporations Rational product family. In addition of drawing
+into its database, which is also supported by other products of Rational
+Software Corporation's Rational product family. In addition to drawing
 diagrams from scratch, it allows reverse engineering diagrams from
 code [#]_.
 
-Rational Rose could be used with **Rational Soda** [#]_ for creating more
+Rational Rose could be used with **Rational Soda** [#]_ to create more
 general architecture documentation. Soda is WYSIWYG (What You See Is What
-You Get) documentation writing tool which allows including diagrams and 
-documentation data from Rational Rose's data model within the written 
-documentation. The both, Rational Rose and Rational Soda, are proprietary
+You Get) documentation writing tool, which allows including diagrams and 
+documentation data from Rational Rose's database to the written 
+documentation. Both Rational Rose and Rational Soda are proprietary
 software and quite expensive for use of small research groups. Problems of 
 direct manipulation and WYSIWYG interfaces are discussed later.
 
@@ -222,21 +224,22 @@
 
 .. [#] http://www.lysator.liu.se/~alla/dia/
 
-**Doxygen** [#]_ is an another Javadoc-like documentation tool, which generates
+**Doxygen** [#]_ is another Javadoc-like documentation tool, which generates
 hypertext documentation from source code of good variety of different languges.
-An intresting feature in Doxygen is that it can also generates and embed
-UML diagrams representing software's class and inheritance hierarchies into 
-class documentation. Also the focused class is higlighted in diagrams on its
-documentation pages. Another enhancement for javadoc in Doxygen is that
-it creates dynamic shrinkable treeview for class hierarchy.
+An intresting feature in Doxygen is that it can also generate and embed 
+into class documentation UML diagrams representing software's class and 
+inheritance hierarchies.
+Also the focused class is higlighted in diagrams on its
+documentation pages. Another enhancement to javadoc in Doxygen is that
+it creates a dynamic shrinkable treeview for class hierarchy.
 
 .. [#] http://www.doxygen.org/
 
-**MetaPhor** [#]_ Project group in University of Jyväskylä have
+**MetaPhor** [#]_ Project in University of Jyväskylä have
 looked for ways of using hypertext in CASE tools [#]_. Results of its research
 have been used in **MetaEdit+** [#]_ meta CASE tool developed by MetaCase 
 Consulting. MetaEdit+ provides bi-directional linking between all its objects
-and interface for reaching linking contexts from diagrams' objects.
+and an interface for reaching linking contexts from diagrams' objects.
 
 :   XXX This should be checked, but metaphor.it.jyu.fi seems to be down :( ]
 
@@ -288,33 +291,36 @@
 view it is still ridiculous even talk about generating the design 
documentation; the
 design should always be made by human, and if the design documentation is for 
human
 reading, it should be also human made. What we could do, is lower the treshold 
of
-writing the design documentation. 
+getting into writing the design documentation. 
 
-For detailed documentation we have selected using Javadoc, since even it's
-not open software it's still free and quite easy to use. Also the likeness of
+For detailed documentation we have decided to use Javadoc, since even though 
+it's
+not free software it's still usable for free and quite easy to use. Also the 
likeness of
 documentation with most of the other Java based projects is a significant 
issue.
 A more difficult issue is to select tools for writing the design documentation 
and
-drawing diagrams into it. The solution should be cheap, and as an open software
+drawing diagrams into it. The solution should be cheap, and as a free software
 project we would prefer other free software. Also the solution should fit well
 to our current working customs.
 
 In addition to the tool selection problem we have to problem of two distinct
-documentation: the human written design documentation and automaticly generated
+pieces of documentation: the human written design documentation and the 
+automatically generated
 detailed Javadoc documentation. During coding the Javadoc documentation is
 often necessary, but the architectural design documentation could be easily 
left
-in the dark reaches of the filesystem. It could be argued that architectural 
-documents are left unused, because relevant parts linked to ongoing work are 
-hard to find. The two distinct documentation (javadoc and design documentation)
-cannot seen as whole. Therefore we should make them work as a whole.
+in the dark reaches of the filesystem. It could be argued that the reason for 
+architectural 
+documents being left unused is that relevant parts linked to ongoing work are 
+hard to find. The distinct pieces (javadoc and design documentation)
+cannot seen as a whole. Therefore we should make them work as a whole.
 
 "Obvious" question: can we increase the overall value by interconnecting the 
-two distinct documentations? 
+two distinct pieces of documentation? 
 
 When looking at a design document, jumping to the javadocs to get the details 
 would be useful, and when looking at a Javadoc, it would be useful
 to be able to see if any design documents refer to that class. 
-We believe that the architecture document will be read more, after it's 
-it's easily reachable from relevant parts of Javadoc.
+We believe that the architecture document will be read more, after it's
+easily reachable from relevant parts of Javadoc.
 This is the starting point for the toolchain developed in this article.