[Gzz-commits] manuscripts ./gzigzag.bib UMLLink/SCRATCH UMLLi...

[Asko Soukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Asko Soukka <address@hidden>    03/02/04 11:23:31

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

Log message:
        hypertext point of view

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/gzigzag.bib.diff?tr1=1.14&tr2=1.15&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/SCRATCH.diff?tr1=1.17&tr2=1.18&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/umllink.rst.diff?tr1=1.58&tr2=1.59&r1=text&r2=text

Patches:
Index: manuscripts/UMLLink/SCRATCH
diff -u manuscripts/UMLLink/SCRATCH:1.17 manuscripts/UMLLink/SCRATCH:1.18
--- manuscripts/UMLLink/SCRATCH:1.17    Tue Feb  4 04:09:16 2003
+++ manuscripts/UMLLink/SCRATCH Tue Feb  4 11:23:31 2003
@@ -1,4 +1,4 @@
-:Stamp: $Id: SCRATCH,v 1.17 2003/02/04 09:09:16 antont Exp $
+:Stamp: $Id: SCRATCH,v 1.18 2003/02/04 16:23:31 humppake Exp $
 
 
  - Perspectives to UML class diagrams, or classifiers in general:
@@ -81,6 +81,38 @@
 
    + the javadoc output filestructure follows the
      hierarchical tree structure of java packages and classes
+
+  (Normal links)::
+
+    reST <-> reST  Alternate View
+                   
+                   this occurs, when the same diagram is 
+                   explicitly referred in two or more architectural 
+                   documents
+
+    javadoc -> javadoc Alternate View? 
+               
+                       We can browse through all classes, which
+                      are part of the diagram. Inside the diagram 
+                       only focusing changes.
+
+    UML in javadoc -> reST    Detail->Summary
+
+    UML in reST -> Javadoc General->Spesific or Summary->Detail
+
+  Trigg classifies the following type-pairs for bi-directional 
+  links, which can are interpreted oppositionally depending on 
+  the direction
+
+    - Generalization/Specification
+    - Abstraction/Example 
+    - Formalization/Application
+    - Summarization/Detail
+    - Simplification/Complication
+
+  ::
+
+     reST <-> javadoc Generalization/Specification  
 
 soved issuas not affecting anymore
 ----------------------------------
Index: manuscripts/UMLLink/umllink.rst
diff -u manuscripts/UMLLink/umllink.rst:1.58 
manuscripts/UMLLink/umllink.rst:1.59
--- manuscripts/UMLLink/umllink.rst:1.58        Tue Feb  4 05:07:38 2003
+++ manuscripts/UMLLink/umllink.rst     Tue Feb  4 11:23:31 2003
@@ -2,7 +2,24 @@
 A free software toolchain for bidirectional linking between UML diagrams and 
Javadoc
 
====================================================================================
 
-:Stamp: $Id: umllink.rst,v 1.58 2003/02/04 10:07:38 antont Exp $
+:Stamp: $Id: umllink.rst,v 1.59 2003/02/04 16:23:31 humppake Exp $
+
+2nd round todo:
+===============
+
+- UML description
+- check metaphor
+- more about stakeholdrer's (antont)
+- javadoc history
+- focus+context menus
+- how our way is placed in 
+  'Hypermedia and cognition: designing for comprehension'
+- xp
+
+3rd round
+=========
+
+- diagrams
 
 Introduction
 ============
@@ -32,9 +49,6 @@
 use UML only for planning and document our software architecture in more 
 general level. We keep UML as a common language for intercommunication 
 within our software developer team and within project's all stakeholders.
-(could these stakeholders be identified and described to some extent
-somewhere? it might be interesting to think also towards users/customers,
-who in some methods (ways of using XP) control use cases themselves)
 In this purpose we prefer more well abstracted and comprehensible
 human drawn diagrams than exact spesifications matching source code to 
 every detail: 
@@ -44,6 +58,10 @@
     For all but the most trivial systems, a diagram represents an elided
     view of the elements that make up a system." [#]_
 
+:   (could these stakeholders be identified and described to some extent
+    somewhere? it might be interesting to think also towards users/customers,
+    who in some methods (ways of using XP) control use cases themselves)
+
 .. [#] booch-jacobson-rumbaugh-uml-user-guide, p.24
 
 Altough, even if the architectural documentation won't fully match with 
@@ -130,6 +148,11 @@
 
 .. [#] boehm-spiral-model p.64
 
+
+``XXXExtreme Programming`` [#]_
+
+.. [#] beck99xp
+
 The nature of our software development process affects also strongly to
 our documentation needs. As we proceed by prototyping and enhancing our
 software step by step, also our documentation should be updated in every
@@ -211,8 +234,9 @@
 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. [ XXX This
-should be checked, but metaphor.it.jyu.fi seems to be down :( ]
+and interface for reaching linking contexts from diagrams' objects.
+
+:   XXX This should be checked, but metaphor.it.jyu.fi seems to be down :( ]
 
 .. [#] metaphor
 .. [#] lyytinen-kerola-metaphor
@@ -230,7 +254,8 @@
 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:
+The two types of documentation are complementary, as demonstrated 
+in the following table:
 
 +-----------------------------------+------------------------------------+
 |       Design docs                 |           Javadoc                  |
@@ -311,9 +336,8 @@
     
 .. [#] edwards-hardman-lost-in-hyperspace, p.123
 
-(See also 'Hypermedia and cognition: designing for comprehension' by Thuring
-et al.  
-http://portal.acm.org/citation.cfm?id=208348&coll=portal&dl=ACM&CFID=7442809&CFTOKEN=15305251#FullText)
+:  See also 'Hypermedia and cognition: designing for comprehension' by Thuring
+   et al. 
http://portal.acm.org/citation.cfm?id=208348&coll=portal&dl=ACM&CFID=7442809&CFTOKEN=15305251#FullText)
 
 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
@@ -458,15 +482,6 @@
 Show instances of arch. docs, javadoc pages &c. Show both diagram and
 then the final hypertext view.``
 
-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 
@@ -475,55 +490,92 @@
 .. [#] Borges's "taxonomy" for animals;
        http://www.multicians.org/thvv/borges-animals.html
 
-Although, we can 
-
-- A Taxonomy of Link Types:
-  
-  Thinking about linking... at first we do have UML->reST and 
-  UML->javadoc links. Because of embedding diagrams implicitly
-  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 
-
-
-  (Normal links)::
-
-    reST <-> reST  Alternate View
-                   
-                   this occurs, when the same diagram is 
-                   explicitly referred in two or more architectural 
-                   documents
-
-    javadoc -> javadoc Alternate View? 
-               
-                       We can browse through all classes, which
-                      are part of the diagram. Inside the diagram 
-                       only focusing changes.
-
-    UML in javadoc -> reST    Detail->Summary
-
-    UML in reST -> Javadoc General->Spesific or Summary->Detail
-
-  Trigg classifies the following type-pairs for bi-directional 
-  links, which can are interpreted oppositionally depending on 
-  the direction
-
-    - Generalization/Specification
-    - Abstraction/Example 
-    - Formalization/Application
-    - Summarization/Detail
-    - Simplification/Complication
-
-  ::
-
-     reST <-> javadoc Generalization/Specification  
-
+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 be used in many different contexts and every single 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.
+
+Because every target document, where a diagram links to, has also a version of 
+the diagram, documents are linked bi-directionally. For example, if document A 
+has a diagram B, which links to document C, document C has also a version of 
+diagram B, which links back to document A. 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. 
+
+When looking only the diagram itself, its links could be divided into two:
+
+ 1) from the diagram into architecture documentation, and 
+ 2) from the diagram into javadoc source code documentation
+
+ Note, that also links from documentation pages to diagram images exist,
+ but hypertext browser mostly interpret them implicitly by showing the 
+ embedded diagrams within the documentation pages.
+
+Still, diagrams are embedded into documentation pages and they should be 
+also seen as part of their context. Therefore diagrams links documentation
+also the following ways:
+
+ 3) a javadoc page to an another javadoc page
+ 4) an architectural documentation page to an another architectural 
documentation
+    page
+ 5) a javadoc page to an architectural documentation page, and
+ 6) an architectural documentation page to a javadoc page
+
+Finally, seeing links as bi-directional will combine links 5) and 6).
+The final list of links would be:
+
+ 1) diagram <-> architecture doc
+ 2) diagram <-> javadoc
+ 3) architectural doc <-> architectural doc
+ 4) javadoc <-> javadoc
+ 5) architectural doc <-> javadoc
+   
+Trigg Randall (1983) have collected a comprehensive taxonomy of different
+link types [#]_, which also covers link types found in our diagrams. 
+Trigg  notes that the physical direction of a link defines the manner in 
+which readers are expected to follow the link. Though, that wont't rule off
+the possibility that link is typed depenging only on it semantic direction. 
+Trigg's taxonomy provides several pairs of such link types.
+
+In our documentation the physical direction of links in a diagram depends by
+the location of explicit include of the diagram. Currently diagrams could be 
+included explicitly only in architectural documents and all the links are 
+physically directed from the including architectural document to the targets
+defined in the diagram. Most of the links from diagras fall into Trigg's
+pairs of links mentioned above.
+
+An interesting situation comes when a diagram is implicitly embedded into two
+document and provides on and implicit link between them. Even in diagram level
+it includes directed links from from diagram object to its details, in document
+level this is undirected. In our documentation this is the case always when 
when
+a javadoc page has an implicitly embedded diagram linking to an another javadoc
+page. Within architecture document this is not the case if the other document 
or
+both of the documents include the diagram explicitly by the author.
+
+
++----------------------------------------------------------------------------------+
+|  Link in our documentation               | Corresponding *normal* link type 
in   |
+|                                          | Trigg's taxonomy                  
    |
++------------------------------------------+---------------------------------------+
+|                                          |                                   
    |
+| 1) diagram <-> architecture doc          | detail / summary                  
    |
+| 2) diagram <-> javadoc                   | detail / summary                  
    |
+|                                          |                                   
    |
+| 3) architectural doc <-> architectural   | explicitly created depends on 
author  |
+|                          doc             | implicitly created is typed as    
    |
+|                                          | alternative view                  
    |
+|                                          |                                   
    |
+| 4) javadoc <-> javadoc                   | alternative view                  
    |
+| 5) architectural doc <-> javadoc         | specification / generalization    
    |
+|                                          |                                   
    |
++------------------------------------------+---------------------------------------+
 
 .. [#] 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.
 
 Implementation
 ==============
Index: manuscripts/gzigzag.bib
diff -u manuscripts/gzigzag.bib:1.14 manuscripts/gzigzag.bib:1.15
--- manuscripts/gzigzag.bib:1.14        Mon Feb  3 08:03:44 2003
+++ manuscripts/gzigzag.bib     Tue Feb  4 11:23:30 2003
@@ -2670,6 +2670,17 @@
 @comment Software development process / Software engineering
 @comment ---------------------------------------------------
 
address@hidden beck99xp,
+    author = "Kent Beck",
+    title = "Embraching change with extreme programming",
+    journal = "IEEE Computer",
+    volume=32,
+    number=10,
+    month="October",
+    pages="70--77",
+    year = 1999
+}
+
 @article{ wand95theoretical,
     author = "Y. Wand and D. Monarchi and J. Parsons",
     title = "Theoretical Foundations for Conceptual Modelling in Information 
Systems Development",