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

[Asko Soukka]

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

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

Log message:
        about design

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/gzigzag.bib.diff?tr1=1.13&tr2=1.14&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/umllink.rst.diff?tr1=1.55&tr2=1.56&r1=text&r2=text

Patches:
Index: manuscripts/UMLLink/umllink.rst
diff -u manuscripts/UMLLink/umllink.rst:1.55 
manuscripts/UMLLink/umllink.rst:1.56
--- manuscripts/UMLLink/umllink.rst:1.55        Fri Jan 31 10:34:03 2003
+++ manuscripts/UMLLink/umllink.rst     Mon Feb  3 08:03:44 2003
@@ -2,13 +2,13 @@
 A free software toolchain for bidirectional linking between UML diagrams and 
Javadoc
 
====================================================================================
 
-:Stamp: $Id: umllink.rst,v 1.55 2003/01/31 15:34:03 humppake Exp $
+:Stamp: $Id: umllink.rst,v 1.56 2003/02/03 13:03:44 humppake Exp $
 
 Introduction
 ============
 
 UML (the Unified Modeling Language), founded mainly by Booch, Jacobson and
-Rumbaugh during 1900s to XXX blah blah [#]_, has become the *de facto* 
+Rumbaugh during 1900s to ``XXX blah blah`` [#]_, has become the *de facto* 
 industry-standard language for specifying, visualizing, constructing, 
 and documenting the products in software engineering. Recently, various 
 approaches have been developed towards unifying software architecture 
@@ -18,7 +18,7 @@
 as a visual language, though it's not primarly designed to be a 
 programming language [#]_.
 
-.. [#] XXX booch-jacobson-rumbaugh-uml-user-guide? 
+.. [#] ``XXX`` booch-jacobson-rumbaugh-uml-user-guide? 
 
 .. [#] harrison-barton-raghavachari00uml-to-java
 
@@ -149,7 +149,7 @@
 java source packages. Besides crosslinking, Javadoc creates indexes and 
 hierarchical trees as navigational aids for locating individual classes.
 
-XXX Little more about Javadoc's history...
+``XXX Little more about Javadoc's history...``
 
 .. [#] friendly95javadoc
 
@@ -290,49 +290,58 @@
 
 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 [#]_. User don't know where she is in the 
documentation 
-network or how to get to some other place that she knows to exist in the 
network.
-
-bi-directional crosslinking between those two distinct
-documentations and select a common naviational metaphor for them both.
+in a nonlinear document [#]_. That means, user don't know where she is in 
+the documentation network or how to get to some other place that she knows
+to exist in the network. In our documentation this gets even more complex,
+because we have two distinct documentations, which should have somehow
+unified navigation.
 
 .. [#] conklin-hypertext, pp.38-40
 
-What can we link?
-
-   "--individuals appear to be attempting to create cognitive
-   representations of hypertext structures in the form of a survey-type
-   map--"
-   [edward-hardman-lost-in-hyperspace, p.123] 
-  
-   "Readers should be allobwed 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."
-   [edward-hardman-lost-in-hyperspace, p.123] 
+Edwards and Hardman [1989] argue that the most appropriate types of 
+navigation devices would be spatially based. 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 allobwed 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. [#]_
     
-   "The mos appropriate types of navigation
-   devices would be those that are spatially based." 
-   [edward-hardman-lost-in-hyperspace, p.123] 
-
-
-   - Conceptual
-
-     + probably no links for javadoc
-     + but we can still enhance the linking within
-       the architectural documentation
-
-   - Specification
-         
-     + can link Java interfaces
+.. [#] edwards-hardman-lost-in-hyperspace, p.123
 
-   - Implementation
-
-     + can link all classes
-
-   - can be useful to link even concept with the class 
-     that eventually implemented it.
-
- - Packages to either Java packages, or the package design document
+We didn't need to look long for a common navigational metatphor to unify our
+two distinct documentation. 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 aren't only shown to
+readres as map of documentation, but they are also used as spatial
+navigation menu. To be more specifig,we can divide our UML-diagrams
+into three classes: conceptual diagrams, specification diagrams and
+implementation diagrams.
+
+Different diagram types can be linked within the architectural documentation
+and between the architectural documentation and javadoc as the follow:
+
+
++-----------------------+------------------------+-----------------------+
+|     Conceptual        |      Specification     |    Implementation     |
++-----------------------+------------------------+-----------------------+
+|                       |                        |                       |
+| + probably no links   | + can link Java        | + can link all        |
+|   for 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     |                        |                       |
+|   class that          |                        |                       |
+|   eventially          |                        |                       |
+|   implement it        |                        |                       |
+|                       |                        |                       |
++-----------------------+------------------------+-----------------------+
 
 Documentation's reader's point of view
 ---------------------------------------
@@ -436,20 +445,30 @@
 Analysis from a hypertext theory point of view
 ==============================================
 
-UML diagram of how architectural documents, UML diagrams and javadoc 
+``UML diagram of how architectural documents, UML diagrams and javadoc 
 pages work. Instead of browsing only in one direction, all associations 
 shown in the diagram should be browsable in either direction! 
 Show instances of arch. docs, javadoc pages &c. Show both diagram and
-then the final hypertext view.
+then the final hypertext view.``
 
-UML diagrams act as multi-ended nexus links, bringing together all 
-documents they relate to. They function like navigation bars on the 
-WWW, except that the same page may have several of them.
+In our software development documentation UML diagrams act as multi-ended
+nexus links, bringing together all documents they relate to. They function
+like navigation bars or context+focusing menus ``[REFSXXX]`` on the WWW, except
+that the same page may have several of them. For example a particular class
+could used in many different contexts and every context could be described 
+by drawing a distinct diagram. Our documentation tool collects all those 
+diagrams into the class documentation page to show all its documented using 
+contexts.
+
+The pure Javadoc organizes class documentation hierarchically according to
+their modules packages, but using a single hierarchy is very limited way
+of organizing things. An illustrative example of this would be Borge's 
+"taxonomy" for animals [#]_.  
 
-- make diagrams work as context+focusing menus to the code documentation
+.. [#] Borges's "taxonomy" for animals;
+       http://www.multicians.org/thvv/borges-animals.html
 
-- Borges's "taxonomy" for animals;
-  http://www.multicians.org/thvv/borges-animals.html
+Although, we can 
 
 - A Taxonomy of Link Types:
   
@@ -458,7 +477,9 @@
   into target documents we can see linking also as 
   bi-directional reST<->javadoc, reST<->reST, and javadoc<->javadoc.
 
-  Mapping our links to types defined by Trigg {trigg-link-taxonomy]
+  Mapping our links to types defined by Trigg 
+
+
   (Normal links)::
 
     reST <-> reST  Alternate View
@@ -490,6 +511,9 @@
   ::
 
      reST <-> javadoc Generalization/Specification  
+
+
+.. [#] trigg-link-taxonomy
 
 From our point of view, the links in the last version cease to be "links"
 and the UML diagrams become objects in their own right.
Index: manuscripts/gzigzag.bib
diff -u manuscripts/gzigzag.bib:1.13 manuscripts/gzigzag.bib:1.14
--- manuscripts/gzigzag.bib:1.13        Fri Jan 31 09:04:05 2003
+++ manuscripts/gzigzag.bib     Mon Feb  3 08:03:44 2003
@@ -1273,7 +1273,7 @@
   howpublished = {\url{http://web.archive.org}}
 }
 
address@hidden erwards-hardman-lost-in-hypersace,
address@hidden edwards-hardman-lost-in-hypersace,
   author = {Edwards, D., & Hardman, L.},
   title = {Lost in Hyperspace: Cognitive Mapping and Navigation in a Hypertext 
Environment.},
   booktitle = {Hypertext: Theory into Practice},