/[gzz]/manuscripts/UMLLink/umllink.rst
ViewVC logotype

Diff of /manuscripts/UMLLink/umllink.rst

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.59 by humppake, Tue Feb 4 16:23:31 2003 UTC revision 1.60 by humppake, Thu Feb 6 01:19:49 2003 UTC
# Line 306  hard to find. The two distinct documenta Line 306  hard to find. The two distinct documenta
306  cannot seen as whole. Therefore we should make them work as a whole.  cannot seen as whole. Therefore we should make them work as a whole.
307    
308  "Obvious" question: can we increase the overall value by interconnecting the  "Obvious" question: can we increase the overall value by interconnecting the
309  two distinct documentations?  two distinct documentations?
310    
311  When looking at a design document, jumping to the javadocs to get the details  When looking at a design document, jumping to the javadocs to get the details
312  would be useful, and when looking at a Javadoc, it would be useful  would be useful, and when looking at a Javadoc, it would be useful
313  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.
314    We believe that the architecture document will be read more, after it's
315    it's easily reachable from relevant parts of Javadoc.
316  This is the starting point for the toolchain developed in this article.  This is the starting point for the toolchain developed in this article.
317    
318    
319  Design  Design
320  ======  ======
321    
# Line 377  and between the architectural documentat Line 380  and between the architectural documentat
380  Documentation's reader's point of view  Documentation's reader's point of view
381  ---------------------------------------  ---------------------------------------
382    
383  When developing  Into current state our documentation evolved through several distinct
384    steps, which will be viewed first from the reader's and then from
385  Step 0; distinct architecture documentation with UML diagrams and javadoc generated from the sourcecode.  the developers point of view.
386  """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""  
387  - UML diagrams in architecture documentation may link within architectural  **Step 0; In the beginning we had a distinct architecture documentation with
388    documentation  UML diagrams and javadoc generated from the sourcecode.** There is probably
389      the most common case. The both documentations could comprehensive and well
390    + objects in UML diagrams which represent parts of the  navigable by their own, but their information is hard to combine, because there
391      documentation are linked to that parts of documentation  is no crosslinking between them.
392    
393  Advantage over paper: NONE  Advantage over paper: NONE
394    
395  Step 1; links from architecture documentation's UML-diagrams into relevant javadoc class documentations  **Step 1; Links from architecture documentation's UML diagrams are created
396  """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""  into relevant javadoc class documentation.** After the first step javadoc was
397  - when we only follow some dummy directed link into some part of  finally reachable from architecture documentation only by clicking relevant
398    javadoc tree, we would lost the class' context in the architecture  classes or packages within embedded UML diagrams. Though, after moving to
399    documentation we left (and moved into javadoc)  the javadoc the context in architectural documentation could be immidiately
400    lost. Also there was no links from javadoc to arcitecture documentation.
 - objects in UML diagrams which represent java classes  
   are linked to javadoc of those classes  
401    
402  Advantage over paper: MARGINAL: automatize cross-indexing  Advantage over paper: MARGINAL: automatize cross-indexing
403    
404  Step 2; embedding UML-diagrams into javadoc, embedded UML-diagrams' objects also work as links  **Step 2; UML-diagrams are implicitly embedded into javadoc and embedded
405  """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""  UML-diagrams' objects also work as links.** After the second step we had
406  - now all objects in UML diagrams could be linked within architecture  diagrams working as menus between the objects that appeared in diagrams.
407    documentation, from architectural documentation to javadoc, within  Though, even a single diagram could be used to traverse between all the
408    javadoc or from javadoc to architecture documentation  documentation pages referred in the diagram, it the original page including
409    the diagram was unreachable from the diagram itself.
 - 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  
410    
411  Advantage over paper: SOME: see the UML diagram contexts of a class,  Advantage over paper: SOME: see the UML diagram contexts of a class,
412  traverse them  traverse them
413    
414  Step 3; backlinks to the architecture documentation  **Step 3; Backlinks to the architecture documentation that include diagrams
415  """""""""""""""""""""""""""""""""""""""""""""""""""  is added.** Finally it's possible to "step back" from class documentation
416  - "focus+context menu"-metaphor for diagrams  back to architecture documentation. After backlinks to the architecture
417    documentation is added, a single diagram include an linked object for all
418     + we highlight the "focused" element of the diagram  architecture documentation and javadoc pages, where it is explicitly or
419            implicitly included. Even the architectural documentation pages were not parts
420  - we can "step back" from class documentation back to architecture  of the original UML diagrams, they are included in the final image on top of the
421    documentation.  UML diagram. Putting all these into same graphical images make the all links
422    look a consistent whole - like a spatial menu. [XXXREFS??] Also the element in
423    + all this (UML and refer backlinks) drawn into diagram for consistency  image representing the current documenta page is focused and target of
424      reasons; this supports "focus+context menu"-metaphor  focus+contex menu is achieved.        
425    
426    + because we can now go to the architectural document from the javadoc,  Because the original location on the diagrams is easily reachable from its
427      we can reduce the size of the diagram in the javadoc by 50%.  every implicit occurerrence in javadoc or in architecture documentation, the
428      size of the implicitly embedded diagram could be reduced by 50%. The name
429      + technical note: hovering mouse over diagram will show  of diagram object is also shown, hovering the pointing device over diagram - also
430        link target class names even on diminished diagrams  on diminished diagrams.
431    
432  Advantage over paper: MAJOR: multi-end links easily traversable,  Advantage over paper: MAJOR: multi-end links easily traversable,
433  structure can be understood  structure can be understood
# Line 442  structure can be understood Line 435  structure can be understood
435  Documentation's developer's point of view  Documentation's developer's point of view
436  -----------------------------------------  -----------------------------------------
437    
438  As little hassle as possible.  On the developer side, creating diagrams within the arhictecture documentation
439    should be as easy and natural as possibel with As little hassle as possible;
440   - minimun barrier to drawing a even small diagram to make  we want to minimun the barrier of drawing even e small diagram to make
441     document more clear, and to new documents  documentation more clear.
442    
443  After Step 1 from user's perspective, the computer has *all* the information  For Step 1, we keep it best to demand explicit links in the UML diagrams. User
444  needed for steps 2 and 3, so *no further changes should be required*.  have to define for each object in UML diagram if it will be linked. For example
445    giving a full java class name with package or a relative path to architecture
446   - only explicit link from diagram object to the class it represents is  documentation page. After Step 1 from user's perspective, the computer has *all*
447     obligatory, all other are implicit  the information needed for complete also steps 2 and 3, so *no further changes
448    should be required*. For example Javadoc comments should not need to be changed
449  For Step 1, it is best to demand explicit links in the UML diagrams.  at all.
450    
451  Steps 2,3:  During steps 2 and 3 computer only embeds diagrams into previously linked
452    documentation pages and creates backlinks to the original documentation
453   - implicitly embed diagrams into relevant code documentation, and  page.
    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  
   
   
454    
455  Analysis from a hypertext theory point of view  Analysis from a hypertext theory point of view
456  ==============================================  ==============================================

Legend:
Removed from v.1.59  
changed lines
  Added in v.1.60

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26