[Gzz-commits] manuscripts/UMLLink umllink.rst

[Asko Soukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Asko Soukka <address@hidden>    03/02/05 20:19:49

Modified files:
        UMLLink        : umllink.rst 

Log message:
        steps

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

Patches:
Index: manuscripts/UMLLink/umllink.rst
diff -u manuscripts/UMLLink/umllink.rst:1.59 
manuscripts/UMLLink/umllink.rst:1.60
--- manuscripts/UMLLink/umllink.rst:1.59        Tue Feb  4 11:23:31 2003
+++ manuscripts/UMLLink/umllink.rst     Wed Feb  5 20:19:49 2003
@@ -2,7 +2,7 @@
 A free software toolchain for bidirectional linking between UML diagrams and 
Javadoc
 
====================================================================================
 
-:Stamp: $Id: umllink.rst,v 1.59 2003/02/04 16:23:31 humppake Exp $
+:Stamp: $Id: umllink.rst,v 1.60 2003/02/06 01:19:49 humppake Exp $
 
 2nd round todo:
 ===============
@@ -306,13 +306,16 @@
 cannot seen as whole. Therefore we should make them work as a whole.
 
 "Obvious" question: can we increase the overall value by interconnecting the 
-two distinct documentations?
+two distinct documentations? 
 
 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.
+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 
+it's easily reachable from relevant parts of Javadoc.
 This is the starting point for the toolchain developed in this article.
 
+
 Design
 ======
 
@@ -377,64 +380,54 @@
 Documentation's reader's point of view
 ---------------------------------------
 
-When developing
-
-Step 0; distinct architecture documentation with UML diagrams and javadoc 
generated from the sourcecode.
-""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
-- UML diagrams in architecture documentation may link within architectural
-  documentation
-  
-  + objects in UML diagrams which represent parts of the 
-    documentation are linked to that parts of documentation
+Into 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.
+
+**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
+navigable by their own, but their information is hard to combine, because 
there 
+is no crosslinking between them.
 
 Advantage over paper: NONE
 
-Step 1; links from architecture documentation's UML-diagrams into relevant 
javadoc class documentations
-"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-- when we only follow some dummy directed link into some part of 
-  javadoc tree, we would lost the class' context in the architecture
-  documentation we left (and moved into javadoc)
-
-- objects in UML diagrams which represent java classes 
-  are linked to javadoc of those classes
+**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.
 
 Advantage over paper: MARGINAL: automatize cross-indexing
 
-Step 2; embedding UML-diagrams into javadoc, embedded UML-diagrams' objects 
also work as links
-""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-- now all objects in UML diagrams could be linked within architecture
-  documentation, from architectural documentation to javadoc, within 
-  javadoc or from javadoc to architecture documentation
-
-- though, this is not yet enough, because we want to know
-  where classes are referred in architecture documentation, to be
-  more exact: where those diagrams implicitly embedded into javadoc
-  are explicitly included
-
-  + "focus+context menu"-metaphor for diagrams needs that we can
-    "step back" from class documentation back to architecture
-    documentation
+**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.
 
 Advantage over paper: SOME: see the UML diagram contexts of a class,
 traverse them
 
-Step 3; backlinks to the architecture documentation
-"""""""""""""""""""""""""""""""""""""""""""""""""""
-- "focus+context menu"-metaphor for diagrams 
-
-   + we highlight the "focused" element of the diagram
-        
-- we can "step back" from class documentation back to architecture
-  documentation. 
-
-  + all this (UML and refer backlinks) drawn into diagram for consistency
-    reasons; this supports "focus+context menu"-metaphor
-
-  + because we can now go to the architectural document from the javadoc,
-    we can reduce the size of the diagram in the javadoc by 50%.
-   
-    + technical note: hovering mouse over diagram will show 
-      link target class names even on diminished diagrams
+**Step 3; Backlinks to the architecture documentation that include diagrams
+is 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 
+focus+contex menu is achieved.        
+
+Because the original location on the diagrams is easily reachable from its
+every implicit occurerrence in javadoc or in architecture 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
@@ -442,36 +435,22 @@
 Documentation's developer's point of view
 -----------------------------------------
 
-As little hassle as possible.
-
- - minimun barrier to drawing a even small diagram to make
-   document more clear, and to new documents
-
-After Step 1 from user's perspective, the computer has *all* the information
-needed for steps 2 and 3, so *no further changes should be required*.
-
- - only explicit link from diagram object to the class it represents is
-   obligatory, all other are implicit
-
-For Step 1, it is best to demand explicit links in the UML diagrams.
-
-Steps 2,3:
-
- - implicitly embed diagrams into relevant code documentation, and
-   backlink code documentation to design documentation
-
-Javadoc comments should not need to be changed at all.
-
-Goals:
-
- - "feeling" that the arch. doc will be read because
-   of the backlinks(!)
-
- - if diagrams try to link objects, which don't exist (e.g. removed
-   Java class), the linking objects will be specially marked 
-   e.g. colored red, or an error when compiling will be given
-
-
+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 
+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
+at all.
+
+During steps 2 and 3 computer only embeds diagrams into previously linked
+documentation pages and creates backlinks to the original documentation
+page. 
 
 Analysis from a hypertext theory point of view
 ==============================================