[Gzz-commits] manuscripts/UMLLink article.rst

[Asko Soukka]

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

Modified files:
        UMLLink        : article.rst 

Log message:
        problem

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

Patches:
Index: manuscripts/UMLLink/article.rst
diff -u manuscripts/UMLLink/article.rst:1.16 
manuscripts/UMLLink/article.rst:1.17
--- manuscripts/UMLLink/article.rst:1.16        Thu Feb 13 08:37:30 2003
+++ manuscripts/UMLLink/article.rst     Thu Feb 13 08:58:28 2003
@@ -5,7 +5,7 @@
 .. Alternative title: "Free Software toolchain for bidirectional 
    linking between UML diagrams and Javadoc"
 
-.. :Stamp: $Id: article.rst,v 1.16 2003/02/13 13:37:30 humppake Exp $
+.. :Stamp: $Id: article.rst,v 1.17 2003/02/13 13:58:28 humppake Exp $
 
 .. Points for HT people
    ====================
@@ -66,7 +66,7 @@
 
    technical architecture:
     * open document base (html) allows:
-       * incorporation of several sources via their own tools (javadoc, rst)
+       * incorporation of several sources via their own tools (Javadoc, reST)
        * unified and bidirectional navigation via after-treatment of 
          all documents
        * result still browsable in WWW
@@ -208,7 +208,7 @@
   E) design and document the module internal structures
   F) write programs
   G) maintain (redesign and redevelopment, keeping documentation
-     up-to-date).
+     up to date).
 
 It should be clear that documentation plays major role in the
 ideal software design process. Steps listed above should produce
@@ -239,7 +239,7 @@
 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
+up to date and rational set of documents available for them could
 ameliorate the Mythical Man Month effect
 [parnas-clements86rational]_(pp255).
 
@@ -275,7 +275,7 @@
 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
+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
@@ -283,6 +283,96 @@
 intercommunication within our group, we believe manually made human
 abstracted documentation serves our purposes best.
 
+Setting of problem
+==================
+
+In our project, as probably in most projects that use Java programming
+language [java-ref]_, the software development documentation is
+divided into two classes: the design documentation and
+Javadoc[friendly95javadoc]_. The design documents cover the most
+important architectural features and are written either before coding
+(for design) or after (for exposition of the architecture). Javadoc,
+on the other hand, is a detailed and fully generated documentation from
+javadoc comments of each class and method in the Java source code.
+
+The two types of documentation are complementary, as demonstrated 
+in the following table:
+
++---------------------------------+-----------------------------------+
+|       Design docs               |             Javadoc               |
++---------------------------------+-----------------------------------+
+|                                 |                                   |
+| - good overall picture.         |  - easy to find a given class,    |
+|                                 |    easy to check all methods      |
+|                                 |                                   |
++---------------------------------+-----------------------------------+
+|                                 |                                   |
+| - little detail,                |  - detailed                       |
+|                                 |                                   |
++---------------------------------+-----------------------------------+
+|                                 |                                   |
+| - may be slightly outdated at   |  - methods and classes *always*   |
+|   any particular time.          |    up to date (generated from     |
+|                                 |    source), doc comments also     |
+|                                 |    usually                        |
+|                                 |                                   |
++---------------------------------+-----------------------------------+
+|                                 |                                   |
+| - hard to find explanations     |  - no overall picture of classes' |
+|   for a particular class.       |    roles                          |
+|                                 |                                   |
++---------------------------------+-----------------------------------+
+|                                 |                                   |
+| - UML diagrams                  |                                   |
+|                                 |                                   |
+| - written and organized by      |                                   |
+|   humans                        |                                   |
+|                                 |                                   |
++---------------------------------+-----------------------------------+
+
+Because Javadoc is fully generated, it is always up to date. Our
+design documentation, though, is updated manually. Of course, it
+should be updated regularly during every design cycle, but in practise
+that won't always happen. From our point of 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 and
+explaining the design using UML diagrams.
+
+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 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 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 design documentation could be easily left in the
+dark reaches of the filesystem. It could be argued that the reason for
+design documents being left unused is that relevant parts linked to
+ongoing work are hard to find. The distinct pieces (Javadoc and the
+design documentation) cannot seen as a whole. Therefore we should make
+them work better as a whole.
+
+"Obvious" question: can we increase the overall value by interconnecting the 
+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 easily reachable from relevant parts of Javadoc. This is the
+starting point for the Free Software toolchain we developed in this
+article: a toolchain for for bidirectional linking between design
+documentation and Javadoc, using UML-diagrams as multi-ended nexus
+links.
+
 Implementation
 ==============
 
@@ -303,7 +393,7 @@
 
 Up to this article, all steps except the last one are implemented. The
 existing tools we selected as the basis for our documentation tool
-are: Javadoc [friendly95javadoc]_, Docutils [goodger02docutils]_, and
+are: Javadoc, Docutils [goodger02docutils]_, and
 our own UML diagram description tool. Further, the UML tool uses
 several free utilies to convert each lexical UML description into
 final *Portable Network Graphics* (PNG) diagram files. Such utilies
@@ -323,7 +413,7 @@
 many of them supporting multiple programming languages including Java.
 
 .. As Javadoc has
-   provided good enough fully generated and up-to-date detailed
+   provided good enough fully generated and up to date detailed
    documentation for our use, we have had no reason to abandon it yet.
 
 UML tool
@@ -410,8 +500,10 @@
   later)
 
 can generate useless diagrams from the code class hierarchy 
+
      * should describe somewhere why these are useles... 
      * uses proprietary GraphViz tool to create diagrams
+
  - How should we discuss WYSIWYG, WYSIAYG/WYSIATI for reST &c? Someone will
    surely ask about that,