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

Diff of /manuscripts/UMLLink/article.rst

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

revision 1.21 by humppake, Thu Feb 13 19:14:10 2003 UTC revision 1.22 by humppake, Fri Feb 14 13:08:35 2003 UTC
# Line 54  Bridging Javadoc to design documentation Line 54  Bridging Javadoc to design documentation
54            * Theories, models, architectures, standards, and frameworks            * Theories, models, architectures, standards, and frameworks
55      * Applications      * Applications
56            * Hypertext in workflow management systems            * Hypertext in workflow management systems
57            * Web-based hypermedia drama            * Web-based hypermedia dramarose
58            * Hypermedia in fiction, scholarship, and technical writing            * Hypermedia in fiction, scholarship, and technical writing
59            * Hypermedia in education and training            * Hypermedia in education and training
60            * Hypermedia and time: narratives and storyboarding            * Hypermedia and time: narratives and storyboarding
# Line 555  Our UML description tool was already imp Line 555  Our UML description tool was already imp
555  documentation linking tool, which finally enabled the bi-directional  documentation linking tool, which finally enabled the bi-directional
556  linking between distinctdocumentations. In the following we discuss  linking between distinctdocumentations. In the following we discuss
557  shortly, how we ended up to use this our own lexical UML language  shortly, how we ended up to use this our own lexical UML language
558  instead of using already existing free diagram drawing tool like Dia  instead of using already existing free direct manipulation diagram
559  [larsson03dia]_, or CASE-tool like AgroUML [tigris03argouml]_.  drawing tools like Dia [larsson03dia]_, or CASE-tool like AgroUML
560    [tigris03argouml]_.
561  .. There exist also such Javadoc like tools, which generate some embedded  
562     diagrams into documentation. Doxygen [heesch03doxygen]_ ,for example,  There exist also such Javadoc like tools, which generate some embedded
563     generates diagrams of class inheritance tree. Also proprietary  diagrams into documentation. Doxygen [heesch03doxygen]_ ,for example,
564     Rational Rose has could be  generates diagrams of class inheritance tree. Also proprietary
565    Rational Rose could be used to reverse engineer UML diagrams and build
566  Although, as discussed earlier, we wanted to use human created diagrams  up to date documentation (with support of Rational Soda) from source
567  in our design documentation.  code [pierce-tilley02connecting-documentation-rose]_. Of course,
568    generated documentation may give well detailed information from the
569   - though, because we are coders, we would prefer UML description  current implementation, but the design documentation should also cover
570     language over menus and dialogs when creating UML diagrams  the future and be rather well abstracted than well detailed.
571    Therefore, we want to avoid being bloated by a large amount of too
572     + we need a ref. of criticism of direct manipulation!  detailed diagrams (meanless for us) and prefer fully human created
573    diagrams in our design documentation.
574       - not necessarily improve performance, users must learn the meaning  
575         of the graphical components, graphic presentation could be  As we want to remove the barrier of drawing at least small diagrams
576         misleading, graphical presentation could take excessive screen display  within the documentation to make it more understandable, the drawing
577         space [Shneiderman-direct-manipulation, p. 64]  method should be easily integrated into current working
578    customs. Because in small softaware development group programmers also
579         probably only the first argument of performance is relevant  write the documentation, the documentation tools shouldn't be gap to
580         anymore... though, creating the graphic presentation for problem  change the programming tool to document writing tools. Even better
581         could lead to using metaphors and those are often  would be that the programming tool could be used as documentation
582         criticized (even by D. Norman :)  tool. Lexical UML description for our UML drawing tool, of course, can
583          be written with any text editor. At least for a programmer, who are
584       - "The dark side of a direct manipulation interface is that  used to describe objects lexically, describing also the UML diagrams
585         you have to directly manipulate everything. Instead of an  could be even more efficient than using direct manipulation drawing
586         executive who gives high-level instructions, the user is  tool.
        reduced to an assembly line worker who must carry out the  
        same task over and over."  
        [gentner-nielsen-anti-mac, p.74]    
   
        limits the precision of our actions to the precision  
        achieved  with eye-hand-mouse coordination (language and  
        mathematics can be more precise)  
        [gentner-nielsen-anti-mac, p.74]    
   
        direct manipulation requires the user to be involved in  
        every action, but sometimes the user may not know  
        what to do  
        [gentner-nielsen-anti-mac, p.74]    
587    
588         "It's as if we have thrown away a million years of         "It's as if we have thrown away a million years of
589         evolution, lost our facility with expressive language,         evolution, lost our facility with expressive language,
590         and been reduced to pointing at objects in the immediate         and been reduced to pointing at objects in the immediate
591         environment. -- We have lost all the power of language, and         environment.-- --We have lost all the power of language, and
592         can no longer talk about objects that are not immidiately         can no longer talk about objects that are not immidiately
593         visible."             visible." [gentner-nielsen96anti-mac]_ (pp74)
        [gentner-nielsen-anti-mac, p.74]    
594    
595       - summaring: direct manipulation could be easy, if there is  The direct manipulation user interface do not necessarily improve
596         a natural graphic presentation for the problem. Even then  performance: users must learn the meaning of the graphical components,
597         it's not necesesserily the most efficient method. Also the  graphic presentation could be misleading, graphical presentation could
598         practical point of using the same writing tool foor coding and  take excessive screen display space
599         documenting.  [shneiderman83direct-manipulation]_ (pp64). The direct manipulation
600    interfaces could be also rather slow to use, since in a such interface
601     + Rose's problem with direct manipulation: a lot of windows,  user have to directly manipulate everything. Instead of an executive
602       menus, dialogies etc... to get direct manipulateable graphic  who gives high-level instructions, the user is reduced to an assembly
603       representation for everything  line worker who must carry out the same task over and over
604    [gentner-nielsen96anti-mac]_ (pp74). The UML langage has XXX different
605    symbols and XXX different connections between them. It is a quite
606    challanging for a direct manipulation interface to make all these
607    alternatives as easily available as they could be typed within lexical
608    description.
609    
610    Describing existing objects for diagram is easy done as lexical
611    description, but the graphical placing of objects is a bit more
612    complicated, although, not impossible.
613    
614    :: figure
615    
616            bigpackage Example
617            class Interface "interface"
618              methods
619                void first()
620    
621            class Derived "interface"
622              inherit Interface
623              methods
624                void second()
625    
626            class Abstract "abstract"
627              methods
628                void third()
629                void fourth()
630    
631            class Implementation
632              realize Derived
633              realize Abstract
634              assoc compos multi(1) - multi(*) role(part_of) Component
635    
636            class Component
637            ------------------------------------------------------------------
638            Derived.c = (100, 100);
639              horizontally(50, derived_h, Interface, Derived, Abstract);
640              vertically(50, derived_v, Derived, Implementation);
641    
642     + though, directmanipulation is only relevant solution for          Component.c = (300, 17);
643       replacing already created object            horizontally(50, component_h, Component);
644    
645            pad = 30;                          
646            Example.nw = Interface.nw + (-pad,pad);
647            Example.se = Component.se + (pad,-pad);
648    
649    .. UML:: umlink-example
650    
651            bigpackage First
652            class Interface "interface"
653              methods
654                void first()
655    
656            class Derived "interface"
657              inherit Interface
658              methods
659                void second()
660    
661            class Abstract "abstract"
662              methods
663                void third()
664                void fourth()
665    
666            class Implementation
667              realize Derived
668              realize Abstract
669              assoc compos multi(1) - multi(*) role(part_of) Component
670    
671            class Component
672    
673            ---
674    
675            Derived.c = (100, 100);
676              horizontally(50, derived_h, Interface, Derived, Abstract);
677              vertically(50, derived_v, Derived, Implementation);
678    
679            Component.c = (300, 17);
680              horizontally(50, component_h, Component);
681    
682            pad = 30;                          
683            First.nw = Interface.nw + (-pad,pad);
684            First.se = Component.se + (pad,-pad);
685    
686  Docutils  Docutils
687  --------  --------

Legend:
Removed from v.1.21  
changed lines
  Added in v.1.22

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