[Gzz-commits] manuscripts/UMLLink umllink.rst

[Tuukka Hastrup]

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

Modified files:
        UMLLink        : umllink.rst 

Log message:
        rewordings trying to ensure understanding (parts before Implementation)

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

Patches:
Index: manuscripts/UMLLink/umllink.rst
diff -u manuscripts/UMLLink/umllink.rst:1.62 
manuscripts/UMLLink/umllink.rst:1.63
--- manuscripts/UMLLink/umllink.rst:1.62        Tue Feb 11 08:52:44 2003
+++ manuscripts/UMLLink/umllink.rst     Tue Feb 11 11:19:03 2003
@@ -2,7 +2,7 @@
 A free software toolchain for bidirectional linking between UML diagrams and 
Javadoc
 
====================================================================================
 
-:Stamp: $Id: umllink.rst,v 1.62 2003/02/11 13:52:44 tuukkah Exp $
+:Stamp: $Id: umllink.rst,v 1.63 2003/02/11 16:19:03 tuukkah Exp $
 
 2nd round todo:
 ===============
@@ -327,21 +327,21 @@
 Design
 ======
 
-The usability of hypertext based documentation may suffer from user's 
+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 [#]_. That means, user don't know where she is in 
-the documentation network or how to get to some other place that she knows
+in a nonlinear document [#]_. 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 documentations, which should have somehow
+because we have two distinct pieces of documentation, which should have somehow
 unified navigation.
 
 .. [#] conklin-hypertext, pp.38-40
 
 Edwards and Hardman [1989] argue that the most appropriate types of 
-navigation devices would be spatially based. According to their research
+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 allobwed to develop a cognitive map of one view of the data 
+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. [#]_
     
@@ -350,17 +350,17 @@
 :  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
-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.
+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. 
 
-Different diagram types can be linked within the architectural documentation
-and between the architectural documentation and javadoc as the follow:
+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 
+architectural documentation and to javadoc as follows:
 
 
 +-----------------------+------------------------+-----------------------+
@@ -368,7 +368,7 @@
 +-----------------------+------------------------+-----------------------+
 |                       |                        |                       |
 | + probably no links   | + can link Java        | + can link all        |
-|   for javadoc         |   interface            |   classes and         |
+|   to javadoc          |   interface            |   classes and         |
 |                       |                        |   packages            |
 | + the design          | + can link also Java   |                       |
 |   documentation       |   packages             |                       |
@@ -379,22 +379,24 @@
 |                       |                        |                       |
 | + concepts could be   |                        |                       |
 |   linked with the     |                        |                       |
-|   class that          |                        |                       |
+|   classes that        |                        |                       |
 |   eventially          |                        |                       |
 |   implement it        |                        |                       |
 |                       |                        |                       |
 +-----------------------+------------------------+-----------------------+
 
-Documentation's reader's point of view
+Documentation reader's point of view
 ---------------------------------------
 
-Into current state our documentation evolved through several distinct
+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 developers point of view.
+the developer's point of view.
 
 **Step 0; In the beginning we had a distinct architecture documentation with 
-UML diagrams and javadoc generated from the sourcecode.** There is probably
-the most common case. The both documentations could comprehensive and well
+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.
 
@@ -402,33 +404,34 @@
 
 **Step 1; Links from architecture documentation's UML diagrams are created
 into relevant javadoc class documentation.** After the first step javadoc was 
-finally reachable from architecture documentation only by clicking relevant
-classes or packages within embedded UML diagrams. Though, after moving to
-the javadoc the context in architectural documentation could be immidiately
-lost. Also there was no links from javadoc to arcitecture documentation.
+finally reachable from architecture documentation simply by clicking the 
+relevant class or package within embedded UML diagrams. Though, after moving to
+the javadoc the context in architectural documentation would be immidiately
+lost. Also there was no links from javadoc to architecture documentation.
 
 Advantage over paper: MARGINAL: automatize cross-indexing
 
-**Step 2; UML-diagrams are implicitly embedded into javadoc and embedded 
-UML-diagrams' objects also work as links.** After the second step we had 
+**Step 2; UML diagrams are implicitly embedded into javadoc and embedded 
+UML diagrams' objects also work as links.** After the second step we had 
 diagrams working as menus between the objects that appeared in diagrams.
-Though, even a single diagram could be used to traverse between all the 
-documentation pages referred in the diagram, it the original page including
-the diagram was unreachable from the diagram itself.
+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
+was unreachable from the diagram itself.
 
 Advantage over paper: SOME: see the UML diagram contexts of a class,
 traverse them
 
-**Step 3; Backlinks to the architecture documentation that include diagrams
-is added.** Finally it's possible to "step back" from class documentation
+**Step 3; Backlinks to the originating architecture documentation 
+are added.** Finally it's possible to "step back" from class documentation
 back to architecture documentation. After backlinks to the architecture
-documentation is added, a single diagram include an linked object for all 
-architecture documentation and javadoc pages, where it is explicitly or 
-implicitly included. Even the architectural documentation pages were not parts
-of the original UML diagrams, they are included in the final image on top of 
the
-UML diagram. Putting all these into same graphical images make the all links 
-look a consistent whole - like a spatial menu. [XXXREFS??] Also the element in
-image representing the current documenta page is focused and target of 
+documentation are added, a single diagram links to all 
+architecture documents and javadoc pages where it is explicitly or 
+implicitly included. Even though the architectural 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. [XXXREFS??] 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
@@ -440,74 +443,76 @@
 Advantage over paper: MAJOR: multi-end links easily traversable,
 structure can be understood
 
-Documentation's developer's point of view
+Documentation developer's point of view
 -----------------------------------------
 
-On the developer side, creating diagrams within the arhictecture documentation
-should be as easy and natural as possibel with As little hassle as possible; 
-we want to minimun the barrier of drawing even e small diagram to make 
+On the developer side, creating diagrams within the architecture documentation
+should be as easy and natural as possible; 
+we want to minimun 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. User
-have to define for each object in UML diagram if it will be linked. For example
-giving a full java class name with package or a relative path to architecture
-documentation page. After Step 1 from user's perspective, the computer has 
*all*
-the information needed for complete also steps 2 and 3, so *no further changes 
-should be required*. For example Javadoc comments should not need to be changed
+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 architecture
+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 only embeds diagrams into previously linked
-documentation pages and creates backlinks to the original documentation
-page. 
+During steps 2 and 3 computer simply embeds diagrams into previously linked
+documentation pages and creates backlinks to the initiating documentation
+pages. 
 
-Analysis from a hypertext theory point of view
+Analysis from a hypertext-theory point of view
 ==============================================
 
 ``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.``
+Show instances of arch. docs, javadoc pages &c. Show both the diagram and
+the final hypertext view.``
 
 The pure Javadoc organizes class documentation hierarchically according to
-their modules packages, but using a single hierarchy is very limited way
+their containing 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 [#]_.  
 
+XXX Do we need this for HT people?
+
 .. [#] Borges's "taxonomy" for animals;
        http://www.multicians.org/thvv/borges-animals.html
 
 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 
+that the same page may have several of them. For example, a particular class
+could be used in many different contexts and each 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.
+usage contexts.
 
-Because every target document, where a diagram links to, has also a version of 
+Because every target document which a diagram links 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 
+the final 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:
+Looking at the diagram itself, its links can 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 
+ Note that also links from documentation pages to diagram images exist,
+ but hypertext browsers usually 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:
+Diagrams embedded into documentation pages should still be 
+also seen as part of their context. Therefore diagrams link documentation
+also in the following ways:
 
  3) a javadoc page to an another javadoc page
- 4) an architectural documentation page to an another architectural 
documentation
+ 4) an architectural documentation page to another architectural documentation
     page
  5) a javadoc page to an architectural documentation page, and
  6) an architectural documentation page to a javadoc page
@@ -524,24 +529,26 @@
 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. 
+which readers are expected to follow the link. However, that won't rule off
+the possibility that link is typed depending only on its 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 
+In our documentation the physical direction of links in a diagram depends on
+the location of explicit inclusion of the diagram. Currently diagrams can 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
+defined in the diagram. Most of the links from diagrams fall into Trigg's
 pairs of links mentioned above.
 
+(XXX Gets difficult to understand)
 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.
+documents and provides an implicit link between them. Although on diagram level
+it includes directed links from a diagram object to its details, on document
+level the links are undirected. In our documentation this is the case always 
+when
+a Javadoc page has an implicitly embedded diagram linking to 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.
 
 
 
+----------------------------------------------------------------------------------+
@@ -567,7 +574,7 @@
 Implementation
 ==============
 
-(We found no open source alternativa to our own development, which 
+(We found no Free Software alternative to our own development, which 
 combines all the good parts we need from previous tools without
 reformin dramatically our workin culture.)