/[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.55 by humppake, Fri Jan 31 15:34:03 2003 UTC revision 1.56 by humppake, Mon Feb 3 13:03:44 2003 UTC
# Line 8  Introduction Line 8  Introduction
8  ============  ============
9    
10  UML (the Unified Modeling Language), founded mainly by Booch, Jacobson and  UML (the Unified Modeling Language), founded mainly by Booch, Jacobson and
11  Rumbaugh during 1900s to XXX blah blah [#]_, has become the *de facto*  Rumbaugh during 1900s to ``XXX blah blah`` [#]_, has become the *de facto*
12  industry-standard language for specifying, visualizing, constructing,  industry-standard language for specifying, visualizing, constructing,
13  and documenting the products in software engineering. Recently, various  and documenting the products in software engineering. Recently, various
14  approaches have been developed towards unifying software architecture  approaches have been developed towards unifying software architecture
# Line 18  the code [#]_. Nowadays UML seem to be t Line 18  the code [#]_. Nowadays UML seem to be t
18  as a visual language, though it's not primarly designed to be a  as a visual language, though it's not primarly designed to be a
19  programming language [#]_.  programming language [#]_.
20    
21  .. [#] XXX booch-jacobson-rumbaugh-uml-user-guide?  .. [#] ``XXX`` booch-jacobson-rumbaugh-uml-user-guide?
22    
23  .. [#] harrison-barton-raghavachari00uml-to-java  .. [#] harrison-barton-raghavachari00uml-to-java
24    
# Line 149  analyzing class hierarchies and includin Line 149  analyzing class hierarchies and includin
149  java source packages. Besides crosslinking, Javadoc creates indexes and  java source packages. Besides crosslinking, Javadoc creates indexes and
150  hierarchical trees as navigational aids for locating individual classes.  hierarchical trees as navigational aids for locating individual classes.
151    
152  XXX Little more about Javadoc's history...  ``XXX Little more about Javadoc's history...``
153    
154  .. [#] friendly95javadoc  .. [#] friendly95javadoc
155    
# Line 290  Design Line 290  Design
290    
291  The usability of hypertext based documentation may suffer from user's  The usability of hypertext based documentation may suffer from user's
292  disorientation: the tendency to lose one's sense of location and direction  disorientation: the tendency to lose one's sense of location and direction
293  in a nonlinear document [#]_. User don't know where she is in the documentation  in a nonlinear document [#]_. That means, user don't know where she is in
294  network or how to get to some other place that she knows to exist in the network.  the documentation network or how to get to some other place that she knows
295    to exist in the network. In our documentation this gets even more complex,
296  bi-directional crosslinking between those two distinct  because we have two distinct documentations, which should have somehow
297  documentations and select a common naviational metaphor for them both.  unified navigation.
298    
299  .. [#] conklin-hypertext, pp.38-40  .. [#] conklin-hypertext, pp.38-40
300    
301  What can we link?  Edwards and Hardman [1989] argue that the most appropriate types of
302    navigation devices would be spatially based. According to their research
303     "--individuals appear to be attempting to create cognitive  individuals appear to be attempting to create cognitive representations of
304     representations of hypertext structures in the form of a survey-type  hypertext structures in the form of a survey-type map. They conlude that
305     map--"  users should be allobwed to develop a cognitive map of one view of the data
306     [edward-hardman-lost-in-hyperspace, p.123]  structure before being given the opinion of navigating through the data some
307      other way. [#]_
    "Readers should be allobwed 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."  
    [edward-hardman-lost-in-hyperspace, p.123]  
308            
309     "The mos appropriate types of navigation  .. [#] edwards-hardman-lost-in-hyperspace, p.123
    devices would be those that are spatially based."  
    [edward-hardman-lost-in-hyperspace, p.123]  
   
   
    - Conceptual  
   
      + probably no links for javadoc  
      + but we can still enhance the linking within  
        the architectural documentation  
   
    - Specification  
             
      + can link Java interfaces  
310    
311     - Implementation  We didn't need to look long for a common navigational metatphor to unify our
312    two distinct documentation. Since the most of our UML-diagrams included objects
313       + can link all classes  representing certain Java-classes, it was clear to use those diagrams
314    for cross documential navigation. UML-diagrams aren't only shown to
315     - can be useful to link even concept with the class  readres as map of documentation, but they are also used as spatial
316       that eventually implemented it.  navigation menu. To be more specifig,we can divide our UML-diagrams
317    into three classes: conceptual diagrams, specification diagrams and
318   - Packages to either Java packages, or the package design document  implementation diagrams.
319    
320    Different diagram types can be linked within the architectural documentation
321    and between the architectural documentation and javadoc as the follow:
322    
323    
324    +-----------------------+------------------------+-----------------------+
325    |     Conceptual        |      Specification     |    Implementation     |
326    +-----------------------+------------------------+-----------------------+
327    |                       |                        |                       |
328    | + probably no links   | + can link Java        | + can link all        |
329    |   for javadoc         |   interface            |   classes and         |
330    |                       |                        |   packages            |
331    | + the design          | + can link also Java   |                       |
332    |   documentation       |   packages             |                       |
333    |   packages could be   |                        |                       |
334    |   linked withing the  |                        |                       |
335    |   architectural       |                        |                       |
336    |   documentation       |                        |                       |
337    |                       |                        |                       |
338    | + concepts could be   |                        |                       |
339    |   linked with the     |                        |                       |
340    |   class that          |                        |                       |
341    |   eventially          |                        |                       |
342    |   implement it        |                        |                       |
343    |                       |                        |                       |
344    +-----------------------+------------------------+-----------------------+
345    
346  Documentation's reader's point of view  Documentation's reader's point of view
347  ---------------------------------------  ---------------------------------------
# Line 436  Goals: Line 445  Goals:
445  Analysis from a hypertext theory point of view  Analysis from a hypertext theory point of view
446  ==============================================  ==============================================
447    
448  UML diagram of how architectural documents, UML diagrams and javadoc  ``UML diagram of how architectural documents, UML diagrams and javadoc
449  pages work. Instead of browsing only in one direction, all associations  pages work. Instead of browsing only in one direction, all associations
450  shown in the diagram should be browsable in either direction!  shown in the diagram should be browsable in either direction!
451  Show instances of arch. docs, javadoc pages &c. Show both diagram and  Show instances of arch. docs, javadoc pages &c. Show both diagram and
452  then the final hypertext view.  then the final hypertext view.``
453    
454  UML diagrams act as multi-ended nexus links, bringing together all  In our software development documentation UML diagrams act as multi-ended
455  documents they relate to. They function like navigation bars on the  nexus links, bringing together all documents they relate to. They function
456  WWW, except that the same page may have several of them.  like navigation bars or context+focusing menus ``[REFSXXX]`` on the WWW, except
457    that the same page may have several of them. For example a particular class
458    could used in many different contexts and every context could be described
459    by drawing a distinct diagram. Our documentation tool collects all those
460    diagrams into the class documentation page to show all its documented using
461    contexts.
462    
463    The pure Javadoc organizes class documentation hierarchically according to
464    their modules packages, but using a single hierarchy is very limited way
465    of organizing things. An illustrative example of this would be Borge's
466    "taxonomy" for animals [#]_.  
467    
468  - make diagrams work as context+focusing menus to the code documentation  .. [#] Borges's "taxonomy" for animals;
469           http://www.multicians.org/thvv/borges-animals.html
470    
471  - Borges's "taxonomy" for animals;  Although, we can
   http://www.multicians.org/thvv/borges-animals.html  
472    
473  - A Taxonomy of Link Types:  - A Taxonomy of Link Types:
474        
# Line 458  WWW, except that the same page may have Line 477  WWW, except that the same page may have
477    into target documents we can see linking also as    into target documents we can see linking also as
478    bi-directional reST<->javadoc, reST<->reST, and javadoc<->javadoc.    bi-directional reST<->javadoc, reST<->reST, and javadoc<->javadoc.
479    
480    Mapping our links to types defined by Trigg {trigg-link-taxonomy]    Mapping our links to types defined by Trigg
481    
482    
483    (Normal links)::    (Normal links)::
484    
485      reST <-> reST  Alternate View      reST <-> reST  Alternate View
# Line 491  WWW, except that the same page may have Line 512  WWW, except that the same page may have
512    
513       reST <-> javadoc Generalization/Specification         reST <-> javadoc Generalization/Specification  
514    
515    
516    .. [#] trigg-link-taxonomy
517    
518  From our point of view, the links in the last version cease to be "links"  From our point of view, the links in the last version cease to be "links"
519  and the UML diagrams become objects in their own right.  and the UML diagrams become objects in their own right.
520    

Legend:
Removed from v.1.55  
changed lines
  Added in v.1.56

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