/[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.58 by antont, Tue Feb 4 10:07:38 2003 UTC revision 1.59 by humppake, Tue Feb 4 16:23:31 2003 UTC
# Line 4  A free software toolchain for bidirectio Line 4  A free software toolchain for bidirectio
4    
5  :Stamp: $Id$  :Stamp: $Id$
6    
7    2nd round todo:
8    ===============
9    
10    - UML description
11    - check metaphor
12    - more about stakeholdrer's (antont)
13    - javadoc history
14    - focus+context menus
15    - how our way is placed in
16      'Hypermedia and cognition: designing for comprehension'
17    - xp
18    
19    3rd round
20    =========
21    
22    - diagrams
23    
24  Introduction  Introduction
25  ============  ============
26    
# Line 32  fully using UML, we tend still to define Line 49  fully using UML, we tend still to define
49  use UML only for planning and document our software architecture in more  use UML only for planning and document our software architecture in more
50  general level. We keep UML as a common language for intercommunication  general level. We keep UML as a common language for intercommunication
51  within our software developer team and within project's all stakeholders.  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)  
52  In this purpose we prefer more well abstracted and comprehensible  In this purpose we prefer more well abstracted and comprehensible
53  human drawn diagrams than exact spesifications matching source code to  human drawn diagrams than exact spesifications matching source code to
54  every detail:  every detail:
# Line 44  every detail: Line 58  every detail:
58      For all but the most trivial systems, a diagram represents an elided      For all but the most trivial systems, a diagram represents an elided
59      view of the elements that make up a system." [#]_      view of the elements that make up a system." [#]_
60    
61    :   (could these stakeholders be identified and described to some extent
62        somewhere? it might be interesting to think also towards users/customers,
63        who in some methods (ways of using XP) control use cases themselves)
64    
65  .. [#] booch-jacobson-rumbaugh-uml-user-guide, p.24  .. [#] booch-jacobson-rumbaugh-uml-user-guide, p.24
66    
67  Altough, even if the architectural documentation won't fully match with  Altough, even if the architectural documentation won't fully match with
# Line 130  phases [#]_: Line 148  phases [#]_:
148    
149  .. [#] boehm-spiral-model p.64  .. [#] boehm-spiral-model p.64
150    
151    
152    ``XXXExtreme Programming`` [#]_
153    
154    .. [#] beck99xp
155    
156  The nature of our software development process affects also strongly to  The nature of our software development process affects also strongly to
157  our documentation needs. As we proceed by prototyping and enhancing our  our documentation needs. As we proceed by prototyping and enhancing our
158  software step by step, also our documentation should be updated in every  software step by step, also our documentation should be updated in every
# Line 211  it creates dynamic shrinkable treeview f Line 234  it creates dynamic shrinkable treeview f
234  looked for ways of using hypertext in CASE tools [#]_. Results of its research  looked for ways of using hypertext in CASE tools [#]_. Results of its research
235  have been used in **MetaEdit+** [#]_ meta CASE tool developed by MetaCase  have been used in **MetaEdit+** [#]_ meta CASE tool developed by MetaCase
236  Consulting. MetaEdit+ provides bi-directional linking between all its objects  Consulting. MetaEdit+ provides bi-directional linking between all its objects
237  and interface for reaching linking contexts from diagrams' objects. [ XXX This  and interface for reaching linking contexts from diagrams' objects.
238  should be checked, but metaphor.it.jyu.fi seems to be down :( ]  
239    :   XXX This should be checked, but metaphor.it.jyu.fi seems to be down :( ]
240    
241  .. [#] metaphor  .. [#] metaphor
242  .. [#] lyytinen-kerola-metaphor  .. [#] lyytinen-kerola-metaphor
# Line 230  architectural features and are written e Line 254  architectural features and are written e
254  and fully generated documentation from javadoc comments of each class and method  and fully generated documentation from javadoc comments of each class and method
255  in the java source code.  in the java source code.
256    
257  The two types of documentation are complementary, as demonstrated in the following table:  The two types of documentation are complementary, as demonstrated
258    in the following table:
259    
260  +-----------------------------------+------------------------------------+  +-----------------------------------+------------------------------------+
261  |       Design docs                 |           Javadoc                  |  |       Design docs                 |           Javadoc                  |
# Line 311  other way. [#]_ Line 336  other way. [#]_
336            
337  .. [#] edwards-hardman-lost-in-hyperspace, p.123  .. [#] edwards-hardman-lost-in-hyperspace, p.123
338    
339  (See also 'Hypermedia and cognition: designing for comprehension' by Thuring  :  See also 'Hypermedia and cognition: designing for comprehension' by Thuring
340  et al.       et al. http://portal.acm.org/citation.cfm?id=208348&coll=portal&dl=ACM&CFID=7442809&CFTOKEN=15305251#FullText)
 http://portal.acm.org/citation.cfm?id=208348&coll=portal&dl=ACM&CFID=7442809&CFTOKEN=15305251#FullText)  
341    
342  We didn't need to look long for a common navigational metatphor to unify our  We didn't need to look long for a common navigational metatphor to unify our
343  two distinct documentation. Since the most of our UML-diagrams included objects  two distinct documentation. Since the most of our UML-diagrams included objects
# Line 458  shown in the diagram should be browsable Line 482  shown in the diagram should be browsable
482  Show instances of arch. docs, javadoc pages &c. Show both diagram and  Show instances of arch. docs, javadoc pages &c. Show both diagram and
483  then the final hypertext view.``  then the final hypertext view.``
484    
 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.  
   
485  The pure Javadoc organizes class documentation hierarchically according to  The pure Javadoc organizes class documentation hierarchically according to
486  their modules packages, but using a single hierarchy is very limited way  their modules packages, but using a single hierarchy is very limited way
487  of organizing things. An illustrative example of this would be Borge's  of organizing things. An illustrative example of this would be Borge's
# Line 475  of organizing things. An illustrative ex Line 490  of organizing things. An illustrative ex
490  .. [#] Borges's "taxonomy" for animals;  .. [#] Borges's "taxonomy" for animals;
491         http://www.multicians.org/thvv/borges-animals.html         http://www.multicians.org/thvv/borges-animals.html
492    
493  Although, we can  In our software development documentation UML diagrams act as multi-ended
494    nexus links, bringing together all documents they relate to. They function
495  - A Taxonomy of Link Types:  like navigation bars or context+focusing menus ``[REFSXXX]`` on the WWW, except
496      that the same page may have several of them. For example a particular class
497    Thinking about linking... at first we do have UML->reST and  could be used in many different contexts and every single context could be
498    UML->javadoc links. Because of embedding diagrams implicitly  described by drawing a distinct diagram. Our documentation tool collects all
499    into target documents we can see linking also as  those diagrams into the class documentation page to show all its documented
500    bi-directional reST<->javadoc, reST<->reST, and javadoc<->javadoc.  using contexts.
501    
502    Mapping our links to types defined by Trigg  Because every target document, where a diagram links to, has also a version of
503    the diagram, documents are linked bi-directionally. For example, if document A
504    has a diagram B, which links to document C, document C has also a version of
505    (Normal links)::  diagram B, which links back to document A. From our point of view, the links in
506    the last version cease to be "links" and the UML diagrams become objects in
507      reST <-> reST  Alternate View  their own right.
508                      
509                     this occurs, when the same diagram is  When looking only the diagram itself, its links could be divided into two:
510                     explicitly referred in two or more architectural  
511                     documents   1) from the diagram into architecture documentation, and
512     2) from the diagram into javadoc source code documentation
513      javadoc -> javadoc Alternate View?  
514                   Note, that also links from documentation pages to diagram images exist,
515                         We can browse through all classes, which   but hypertext browser mostly interpret them implicitly by showing the
516                         are part of the diagram. Inside the diagram   embedded diagrams within the documentation pages.
517                         only focusing changes.  
518    Still, diagrams are embedded into documentation pages and they should be
519      UML in javadoc -> reST    Detail->Summary  also seen as part of their context. Therefore diagrams links documentation
520    also the following ways:
521      UML in reST -> Javadoc General->Spesific or Summary->Detail  
522     3) a javadoc page to an another javadoc page
523    Trigg classifies the following type-pairs for bi-directional   4) an architectural documentation page to an another architectural documentation
524    links, which can are interpreted oppositionally depending on      page
525    the direction   5) a javadoc page to an architectural documentation page, and
526     6) an architectural documentation page to a javadoc page
527      - Generalization/Specification  
528      - Abstraction/Example  Finally, seeing links as bi-directional will combine links 5) and 6).
529      - Formalization/Application  The final list of links would be:
530      - Summarization/Detail  
531      - Simplification/Complication   1) diagram <-> architecture doc
532     2) diagram <-> javadoc
533    ::   3) architectural doc <-> architectural doc
534     4) javadoc <-> javadoc
535       reST <-> javadoc Generalization/Specification     5) architectural doc <-> javadoc
536      
537    Trigg Randall (1983) have collected a comprehensive taxonomy of different
538    link types [#]_, which also covers link types found in our diagrams.
539    Trigg  notes that the physical direction of a link defines the manner in
540    which readers are expected to follow the link. Though, that wont't rule off
541    the possibility that link is typed depenging only on it semantic direction.
542    Trigg's taxonomy provides several pairs of such link types.
543    
544    In our documentation the physical direction of links in a diagram depends by
545    the location of explicit include of the diagram. Currently diagrams could be
546    included explicitly only in architectural documents and all the links are
547    physically directed from the including architectural document to the targets
548    defined in the diagram. Most of the links from diagras fall into Trigg's
549    pairs of links mentioned above.
550    
551    An interesting situation comes when a diagram is implicitly embedded into two
552    document and provides on and implicit link between them. Even in diagram level
553    it includes directed links from from diagram object to its details, in document
554    level this is undirected. In our documentation this is the case always when when
555    a javadoc page has an implicitly embedded diagram linking to an another javadoc
556    page. Within architecture document this is not the case if the other document or
557    both of the documents include the diagram explicitly by the author.
558    
559    
560    +----------------------------------------------------------------------------------+
561    |  Link in our documentation               | Corresponding *normal* link type in   |
562    |                                          | Trigg's taxonomy                      |
563    +------------------------------------------+---------------------------------------+
564    |                                          |                                       |
565    | 1) diagram <-> architecture doc          | detail / summary                      |
566    | 2) diagram <-> javadoc                   | detail / summary                      |
567    |                                          |                                       |
568    | 3) architectural doc <-> architectural   | explicitly created depends on author  |
569    |                          doc             | implicitly created is typed as        |
570    |                                          | alternative view                      |
571    |                                          |                                       |
572    | 4) javadoc <-> javadoc                   | alternative view                      |
573    | 5) architectural doc <-> javadoc         | specification / generalization        |
574    |                                          |                                       |
575    +------------------------------------------+---------------------------------------+
576    
577  .. [#] trigg-link-taxonomy  .. [#] trigg-link-taxonomy
578    
 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.  
579    
580  Implementation  Implementation
581  ==============  ==============

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

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