[Gzz-commits] manuscripts/UMLLink article.rst

[Asko Soukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Asko Soukka <address@hidden>    03/02/13 09:39:26

Modified files:
        UMLLink        : article.rst 

Log message:
        design sketch for tuukkah

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

Patches:
Index: manuscripts/UMLLink/article.rst
diff -u manuscripts/UMLLink/article.rst:1.17 
manuscripts/UMLLink/article.rst:1.18
--- manuscripts/UMLLink/article.rst:1.17        Thu Feb 13 08:58:28 2003
+++ manuscripts/UMLLink/article.rst     Thu Feb 13 09:39:26 2003
@@ -5,7 +5,7 @@
 .. Alternative title: "Free Software toolchain for bidirectional 
    linking between UML diagrams and Javadoc"
 
-.. :Stamp: $Id: article.rst,v 1.17 2003/02/13 13:58:28 humppake Exp $
+.. :Stamp: $Id: article.rst,v 1.18 2003/02/13 14:39:26 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]_(pp12), 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
@@ -160,7 +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]_(pp24) 
+   [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
@@ -199,15 +199,15 @@
 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):
+[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
+  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
@@ -221,19 +221,19 @@
 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
+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)
+  [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)
+  [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
@@ -241,7 +241,7 @@
 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).
+[parnas-clements86rational]_ (pp255).
 
 Because our group is doing experimental research with a rather small
 group and as an open Free Software project, we need a flexible model
@@ -250,7 +250,7 @@
 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):
+and every cycle has the following phases [boehm88spiral-model]_ (pp64):
 
  * analysis: determining objectives, alternatives, constraints
  * design: evaluating alternatives, identifying and resolving risks
@@ -299,35 +299,25 @@
 in the following table:
 
 +---------------------------------+-----------------------------------+
-|       Design docs               |             Javadoc               |
+| **Design documentation**        | **Javadoc**                       |
 +---------------------------------+-----------------------------------+
-|                                 |                                   |
-| - good overall picture.         |  - easy to find a given class,    |
-|                                 |    easy to check all methods      |
-|                                 |                                   |
+| good overall picture.           | easy to find a given class,       |
+|                                 | easy to check all methods         |
 +---------------------------------+-----------------------------------+
-|                                 |                                   |
-| - little detail,                |  - detailed                       |
-|                                 |                                   |
+| 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                        |
-|                                 |                                   |
+| 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                          |
-|                                 |                                   |
+| hard to find explanations       | no overall picture of classes'    |
+| for a particular class.         | roles                             |
 +---------------------------------+-----------------------------------+
-|                                 |                                   |
-| - UML diagrams                  |                                   |
-|                                 |                                   |
-| - written and organized by      |                                   |
-|   humans                        |                                   |
-|                                 |                                   |
+| UML diagrams                    |                                   |
++---------------------------------+-----------------------------------+
+| written and organized by        |                                   |
+| humans                          |                                   |
 +---------------------------------+-----------------------------------+
 
 Because Javadoc is fully generated, it is always up to date. Our
@@ -370,9 +360,151 @@
 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
+documentation and Javadoc, using UML diagrams as multi-ended nexus
 links.
 
+Design
+======
+
+XXX Hypertext blaablaa something...
+-----------------------------------
+
+The usability of hypertext-based documentation may suffer from user's
+disorientation: the tendency to lose one's sense of location and
+direction in a nonlinear document [conklin87hypertext ]_
+(pp38--40). That means, users don't know where they are in the
+documentation network or how to get to some other place that they know
+to exist in the network. In our documentation this gets even more
+complex, because we have two distinct pieces of documentation, which
+should have somehow unified navigation.
+
+Edwards and Hardman [edwards-hardman89lost-in-hyperspace]_ argue that
+the most appropriate types of navigation devices would be based on
+spatiality. According to their research, individuals appear to be
+attempting to create cognitive representations of hypertext structures
+in the form of a survey-type map. They conlude that users should be
+allowed to develop a cognitive map of one view of the data structure
+before being given the opinion of navigating through the data some
+other way. [edwards-hardman89lost-in-hyperspace]_ (pp123)
+    
+We didn't need to look long for a common navigational metaphor to
+unify the two distinct pieces. Since the most of our UML diagrams
+included objects representing certain Java classes, it was clear to
+use those diagrams for cross-documential navigation. UML diagrams not
+only show the readers a map of documentation but also perform as
+spatial navigation menus.
+
+XXX linking UML diagrams
+------------------------
+
+Looking closer, we can divide our UML diagrams into three classes:
+conceptual diagrams, specification diagrams and implementation
+diagrams. Different diagram types can be linked within the
+design documentation and to javadoc as follows:
+
++-----------------------+-----------------------+--------------------+
+|**Conceptual**         | **Specification**     | **Implementation** |
++-----------------------+-----------------------+--------------------+
+| probably no links     | can link Java         | can link all       |
+| to javadoc            | interface             | classes and        |
+|                       |                       | packages           |
++-----------------------+-----------------------+--------------------+
+| the design            | can link also Java    |                    |
+| documentation         | packages              |                    |
+| packages could be     |                       |                    |
+| linked withing the    |                       |                    |
+| architectural         |                       |                    |
+| documentation         |                       |                    |
++-----------------------+-----------------------+--------------------+
+| concepts could be     |                       |                    |
+| linked with the       |                       |                    |
+| classes that          |                       |                    |
+| eventially            |                       |                    |
+| implement it          |                       |                    |
++-----------------------+-----------------------+--------------------+
+
+Documentation reader's point of view
+---------------------------------------
+
+Before reaching the 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.
+
+**Step 0; The beginning.** In the beginning we had a distinct design
+documentation with UML diagrams and Javadoc generated from the
+sourcecode. This is probably the most common case. The both pieces
+of documentation could comprehensive and well navigable by their own,
+but their information is hard to combine, because there is no
+crosslinking between them.
+
+.. Advantage over paper: NONE
+
+**Step 1; Automatizing cross-indexing.** After the first step links
+from design documentation's UML diagrams are created into relevant
+Javadoc class documentation. Javadoc is finally reachable from design
+documentation simply by clicking the relevant class or package within
+embedded UML diagrams. Though, after moving to the Javadoc the context
+in design documentation would be immidiately lost. Also there is no
+links from Javadoc to design documentation.
+
+.. Advantage over paper: MARGINAL: automatize cross-indexing
+
+**Step 2; UML diagram context of a particular class may be seen and
+traversing between them is possible.** After the second step UML
+diagrams are implicitly embedded into Javadoc and embedded UML
+diagrams' objects also work as multi-end nexus links. We have diagrams
+working as menus between the objects that appear in diagrams.  Though,
+even though a single diagram could be used to traverse between all the
+documentation pages referred to in the diagram, the initiating design
+document is unreachable from the diagram itself.
+
+.. Advantage over paper: SOME: see the UML diagram contexts of a class,
+   traverse them
+
+**Step 3; Multi-end nexus links easily traversable and structure of
+documentation can be understood.** Finally backlinks to the
+originating design documentation are added. It's possible to "step
+back" from class documentation back to design documentation. After
+backlinks to the design documentation are added, a single diagram
+links to all design documents and Javadoc pages where it is explicitly
+or implicitly included. Even though the design documents were not in
+roles in the original UML diagrams, they are included in the final
+image on top of the diagram. Putting all these into one graphical
+image makes the all links look a consistent whole - like a spatial
+menu. In the image, the element that represents the current document
+page is also focused and the objective of focus+contex menu is
+achieved.
+
+Because the original location on the diagrams is easily reachable from its
+every implicit occurerrence in Javadoc or in design documentation, the
+size of the implicitly embedded diagram could be reduced by 50%. The name 
+of diagram object is also shown, hovering the pointing device over diagram - 
also 
+on diminished diagrams.
+
+Advantage over paper: MAJOR: multi-end links easily traversable,
+structure can be understood
+
+Documentation developer's point of view
+-----------------------------------------
+
+On the developer side, creating diagrams within the design
+documentation should be as easy and natural as possible; we want to
+minimum the barrier of drawing even only a small diagram to make
+documentation more clear.
+
+For Step 1, we keep it best to demand explicit links in the UML
+diagrams. Author has to decide for each object in UML diagram whether
+it should be linked, for example, by giving a fully-qualified java
+class name or a relative path to design documentation page. After Step
+1 from author's perspective, the computer has *all* the information
+needed to complete also steps 2 and 3, so *no further changes should
+be required*. For example javadoc comments should not need changes at
+all.
+
+During steps 2 and 3 computer simply embeds diagrams into previously linked
+documentation pages and creates backlinks to the initiating documentation
+pages. 
+
 Implementation
 ==============
 
@@ -559,7 +691,7 @@
   later)
 
 
-- diagrams in the same reST source as the architecture document
+- diagrams in the same reST source as the design document
 
 - separate UML structure from presentation, show structure in easily
   editable text