/[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.52 by humppake, Thu Jan 30 11:47:15 2003 UTC revision 1.53 by humppake, Thu Jan 30 16:19:51 2003 UTC
# Line 171  documentation. Of course more detailed u Line 171  documentation. Of course more detailed u
171  generated from the current source for those members, who are working with  generated from the current source for those members, who are working with
172  particular details. Though, in general documentation rapidly changing details  particular details. Though, in general documentation rapidly changing details
173  would be irrelevant and confusing. Since currently the main purpose for our  would be irrelevant and confusing. Since currently the main purpose for our
174  documentation is help intercommunication within our group, we believe manually  documentation is to help intercommunication within our group, we believe manually
175  made human abstracted documentation serving purposes best.  made human abstracted documentation serving our purposes best.
176        
177  Javadoc  Javadoc
178  -------  -------
179    
180  Javadoc  [#]_ is a hypertext documentation tool developed by Sun  **Javadoc** [#]_ is a hypertext documentation tool developed by Sun
181  Microsystems and delivered with Sun's Java distribution packages [#]_.  Microsystems and delivered with Sun's Java distribution packages [#]_.
182  Javadoc generates detailed and well crosslinked documentation analyzing  Javadoc generates detailed and well crosslinked hypertext documentation
183  classes and including also comments from java source packages. Besides  analyzing class hierarchies and including documentation comments from
184  crosslinking, Javadoc creates indexes and archical trees as navigational  java source packages. Besides crosslinking, Javadoc creates indexes and
185  aids for finding individual classes.  hierarchical trees as navigational aids for locating individual classes.
186    
187  .. [#] http://java.sun.com/j2se/javadoc/  .. [#] http://java.sun.com/j2se/javadoc/
188    
189  .. [#] Java is a trademark of Sun Microsystems  .. [#] Java is a trademark of Sun Microsystems
190    
191  Sun's distribution of Javadoc tools is proprietary, but there exists  Sun's distribution of Javadoc tools is proprietary, but there exists
192  also free software (licensed unde GPL) alternatives like doc++ [#]_,  also free software (licensed unde GPL) alternatives like doc++ [#]_.
193  which can create documentation also from sources of other languages  Doc++ is designed to create hypertext documentation also from sourcefile
194  (e.g. C++).  of other languages (e.g. C, C++, perl).
195    
196  .. [#] http://docpp.sourceforge.net/  .. [#] http://docpp.sourceforge.net/
197    
198  UML  UML
199  ---  ---
200    
201   - diagrams are from human to human  **Rational Rose** [#]_ is quite honored UML design tool. It provides a
202    direct manipulation interface for drawing different kinds of UML diagrams
203     + we don't wan to generate diagrams from the code or generate  into it's data model, which is also supported by other products of Rational
204       code from the diagrams  Software Corporations Rational product family. In addition of drawing
205     + generated diagrams are too detailed to be beneficial  diagrams from scratch, it allows reverse engineering diagrams from
206     + basic architectural diagrams should be done before code anyway  code [#]_.
207       (according to software design process models)  
208    Rational Rose could be used with **Rational Soda** [#]_ for creating more
209  Rational Rose  general architecture documentation. Soda is WYSIWYG (What You See Is What
210    You Get) documentation writing tool which allows including diagrams and
211   - part of rational devtool suite  documentation data from Rational Rose's data model within the written
212    documentation. The both, Rational Rose and Rational Soda, are proprietary
213   - quite comprehensive UML design tool for different diagrams (class,  software and quite expensive for use of small research groups. Problems of
214     sequence, state...) with direct manipulation interface  direct manipulation and WYSIWYG interfaces are discussed later.
215   - can reverse engingeer diagrams from existing source code  
216    .. [#] http://www.rational.com/products/rose/
217   - co-operating with Rational Soda, Soda is WYSIWYG  
218     [pierce-tilley02connecting-documentation-rose]  .. [#] pierce-tilley02connecting-documentation-rose
219    
220   - How should we discuss WYSIWYG, WYSIAYG/WYSIATI for reST &c? Someone will  .. [#] http://www.rational.com/products/soda/
221     surely ask about that,  
222    **Dia** [#]_ is a free software (licensed under GPL) alternative for diagram
223      PARTIAL RESOLUTION:  drawing with direct manipulation user interface. Dia is still more just a
224    drawing than design tool, but it can export diagrams in several formats
225          - proprietarity (really?)  and it has a plugin interface for new drawing object sets.
         - versioning much worse  
           (changes in rtf could probably be compared?)  
         - users = programmers --> used to editing text and compiling,  
           it's the most practical to use the same editor as for coding  
         - lack of good, **extensible** tools  
   
     
    [gentner-nielsen-anti-mac, p.75] collects arguments/argues  
    generally against WYSIWYG.  
   
     - a document has a rich semantic structure that is poorly  
       captured by its appearance on a sceen or printed page  
     - other text representations, such as SGML, distinct the semantic  
       structure and rules for converting the text and semantics into  
       printablepage  
     - WYSIWYG assumes there is only one useful representation of the  
       information: that of the final reports  
     - WYSIWYG assumes people want paper-style reports (and we already  
       live within information flood)  
     - blind users exists  
   
     - Rational Soda is WYSIWYG, maybe this could be discussed under  
       it  
   
  - though, because we are coders, we would prefer UML script  
    language over menus and dialogs when creating UML objects  
   
    + we need a ref. of criticism of direct manipulation!  
   
      - not necessarily improve performance, users must learn the meaning  
        of the graphical components, graphic presentation could be  
        misleading, graphical presentation could take excessive screen display  
        space [Shneiderman-direct-manipulation, p. 64]  
   
        probably only the first argument of performance is relevant  
        anymore... though, creating the graphic presentation for problem  
        could lead to using metaphors and those are often  
        criticized (even by D. Norman :)  
         
      - "The dark side of a direct manipulation interface is that  
        you have to directly manipulate everything. Instead of an  
        executive who gives high-level instructions, the user is  
        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]    
   
        "It's as if we have thrown away a million years of  
        evolution, lost our facility with expressive language,  
        and been reduced to pointing at objects in the immediate  
        environment. -- We have lost all the power of language, and  
        can no longer talk about objects that are not immidiately  
        visible."      
        [gentner-nielsen-anti-mac, p.74]    
   
      - summaring: direct manipulation could be easy, if there is  
        a natural graphic presentation for the problem. Even then  
        it's not necesesserily the most efficient method. Also the  
        practical point of using the same writing tool foor coding and  
        documenting.  
   
    + Rose's problem with direct manipulation: a lot of windows,  
      menus, dialogies etc... to get direct manipulateable graphic  
      representation for everything  
   
    + though, directmanipulation is only relevant solution for  
      replacing already created object  
   
  - proprietary  
   
 Dia  (drawing, generating code templates)  
   
  - Dia [#]_ is a free software (licensed under GPL) diagram  
    creating program with direct manipulation user interface.  
  - more a drawing than a design tool  
226    
227  .. [#] http://www.lysator.liu.se/~alla/dia/  .. [#] http://www.lysator.liu.se/~alla/dia/
228    
229  Doxygen  **Doxygen** [#]_ is an another Javadoc-like documentation tool, which generates
230    hypertext documentation from source code of good variety of different languges.
231   - Doxygen [#]_ is an another Javadoc-like documentation tool, which  An intresting feature in Doxygen is that it can also generates and embed
232     generates hypertext documentation from source code of good variety  UML diagrams representing software's class and inheritance hierarchies into
233     of different languges. An intresting feature in Doxygen is that  class documentation. Also the focused class is higlighted in diagrams on its
234     it generates and embeds UML diagrams representing software's  documentation pages. Another enhancement for javadoc in Doxygen is that
235     class and inheritance hierarchies into class documentation. Also  it creates dynamic shrinkable treeview for class hierarchy.
    the currently viewed class is higlighted in diagrams. Doxygen  
    also creates shrinkable treeview for class hierarchy.  
   
  - can generate useless diagrams from the code class hierarchy  
  - should describe somewhere why these are useles...  
  - uses proprietary GraphViz tool to create diagrams  
236    
237  .. [#] http://www.doxygen.org/  .. [#] http://www.doxygen.org/
238    
239  MetaPhor, hypertext in soft. devel? [metaphor]  **MetaPhor** [#]_ Project group in University of Jyväskylä have
240    looked for ways of using hypertext in CASE tools[#_]. Results of its research
241    have been used in **MetaEdit+**[#]_ meta CASE tool developed by MetaCase
242    Consulting. MetaEdit+ provides bi-directional linking between all its objects
243    and interface for reaching linking contexts from diagrams' objects. [ XXX This
244    should be checked, but metaphor.it.jyu.fi seems to be down :( ]
245    
246    .. [#] metaphor
247    .. [#] lyytinen-kerola-metaphor
248    .. [#] http://www.metacase.com/
249    
  - bi-directional linking of CASE-tool documents/objects (e.g. double  
    clicking an object opens more detailed diagram, backlink could  
    be found from popup-menu... anyway, a lot of menus to select  
    objects for linking or already linked objects to show)  
    [lyytinen-kerola-metaphor]  
   
  - MetaEdit+  
   
    + meta CASE tool; could be made to generate code from the diagrams  
    + could be used to create domain spesific languages, when generating  
      code can really work  
   
 (We found no open source alternativa to our own development, which  
 combines all the good parts we need from previous tools without  
 reformin dramatically our workin culture.)  
250    
251  Setting of problem  Setting of problem
252  ==================  ==================
# Line 397  The two types of documentation are compl Line 301  The two types of documentation are compl
301  |                                        |                                              |  |                                        |                                              |
302  +----------------------------------------+----------------------------------------------+  +----------------------------------------+----------------------------------------------+
303    
304    
305    
306  Problems with the docs:  Problems with the docs:
307    
308   +  Architectural docs easily left in the dark reaches of the filesystem,   +  Architectural docs easily left in the dark reaches of the filesystem,
# Line 424  Problems with the docs: Line 330  Problems with the docs:
330     devices would be those that are spatially based."     devices would be those that are spatially based."
331     [edward-hardman-lost-in-hyperspace, p.123]     [edward-hardman-lost-in-hyperspace, p.123]
332    
333    
334  "Obvious" question: can we increase the overall value by  "Obvious" question: can we increase the overall value by
335  interconnecting the two?  interconnecting the two?
336    
# Line 627  and the UML diagrams become objects in t Line 534  and the UML diagrams become objects in t
534  Implementation  Implementation
535  ==============  ==============
536    
537    (We found no open source alternativa to our own development, which
538    combines all the good parts we need from previous tools without
539    reformin dramatically our workin culture.)
540    
541  + HTML/WWW browsers don't support bi-directional links  + HTML/WWW browsers don't support bi-directional links
542    
543  Goals:  Goals:
# Line 654  reST's filosophy Line 565  reST's filosophy
565    
566  Why UML-language  Why UML-language
567    
568     - Doxygen can generate useless diagrams from the code class hierarchy
569       should describe somewhere why these are useles...
570       uses proprietary GraphViz tool to create diagrams
571    
572    
573     - How should we discuss WYSIWYG, WYSIAYG/WYSIATI for reST &c? Someone will
574       surely ask about that,
575    
576        PARTIAL RESOLUTION:
577    
578            - proprietarity (really?)
579            - versioning much worse
580              (changes in rtf could probably be compared?)
581            - users = programmers --> used to editing text and compiling,
582              it's the most practical to use the same editor as for coding
583            - lack of good, **extensible** tools
584    
585      
586       [gentner-nielsen-anti-mac, p.75] collects arguments/argues
587       generally against WYSIWYG.
588    
589        - a document has a rich semantic structure that is poorly
590          captured by its appearance on a sceen or printed page
591        - other text representations, such as SGML, distinct the semantic
592          structure and rules for converting the text and semantics into
593          printablepage
594        - WYSIWYG assumes there is only one useful representation of the
595          information: that of the final reports
596        - WYSIWYG assumes people want paper-style reports (and we already
597          live within information flood)
598        - blind users exists
599    
600        - Rational Soda is WYSIWYG, maybe this could be discussed under
601          it
602    
603     - though, because we are coders, we would prefer UML script
604       language over menus and dialogs when creating UML objects
605    
606       + we need a ref. of criticism of direct manipulation!
607    
608         - not necessarily improve performance, users must learn the meaning
609           of the graphical components, graphic presentation could be
610           misleading, graphical presentation could take excessive screen display
611           space [Shneiderman-direct-manipulation, p. 64]
612    
613           probably only the first argument of performance is relevant
614           anymore... though, creating the graphic presentation for problem
615           could lead to using metaphors and those are often
616           criticized (even by D. Norman :)
617          
618         - "The dark side of a direct manipulation interface is that
619           you have to directly manipulate everything. Instead of an
620           executive who gives high-level instructions, the user is
621           reduced to an assembly line worker who must carry out the
622           same task over and over."
623           [gentner-nielsen-anti-mac, p.74]  
624    
625           limits the precision of our actions to the precision
626           achieved  with eye-hand-mouse coordination (language and
627           mathematics can be more precise)
628           [gentner-nielsen-anti-mac, p.74]  
629    
630           direct manipulation requires the user to be involved in
631           every action, but sometimes the user may not know
632           what to do
633           [gentner-nielsen-anti-mac, p.74]  
634    
635           "It's as if we have thrown away a million years of
636           evolution, lost our facility with expressive language,
637           and been reduced to pointing at objects in the immediate
638           environment. -- We have lost all the power of language, and
639           can no longer talk about objects that are not immidiately
640           visible."    
641           [gentner-nielsen-anti-mac, p.74]  
642    
643         - summaring: direct manipulation could be easy, if there is
644           a natural graphic presentation for the problem. Even then
645           it's not necesesserily the most efficient method. Also the
646           practical point of using the same writing tool foor coding and
647           documenting.
648    
649       + Rose's problem with direct manipulation: a lot of windows,
650         menus, dialogies etc... to get direct manipulateable graphic
651         representation for everything
652    
653       + though, directmanipulation is only relevant solution for
654         replacing already created object
655    
656    
657  - not strictly necessary; could have used another editor  - not strictly necessary; could have used another editor
658    
659  - minimum barrier to make a diagram (well, at first have to learn our UML-script)  - minimum barrier to make a diagram (well, at first have to learn our UML-script)

Legend:
Removed from v.1.52  
changed lines
  Added in v.1.53

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