/[gzz]/manuscripts/UMLLink/short-paper.rst
ViewVC logotype

Diff of /manuscripts/UMLLink/short-paper.rst

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

revision 1.4 by humppake, Wed Apr 30 14:20:41 2003 UTC revision 1.5 by humppake, Thu May 8 12:34:56 2003 UTC
# Line 33  Bridging Javadoc and design documentatio Line 33  Bridging Javadoc and design documentatio
33     - [humppake] couldn't find yet     - [humppake] couldn't find yet
34    
35    
36  Sketching  Abstract
37  =========  ========
38    
39  - short description about problem:  We present a navigational aid for documentation used in software
40    * programming language specific tools like javadoc do generate  development. Based on using readily-authored UML diagrams as multi-ended
41      well navigable documentations from source code  links, we hypertexturally connect two distinct areas of documentation: design
42    * above them is a human written abstraction to the system  documents and javadoc program code documentation.
43      as whole - the design documentation  
44    * how to make these documentation fragments interconnected  .. Connecting the distinct areas is essential because it could help new
45      with each other with minimum additional work     developers in getting productive and supports development processes
46       where both design and implementation change continuously.
47    Should be searched previous papers, which have research  
48    quostions alike. Check at first the keywords given by referees  Introduction
49    of UMLLink article.  ============
50    
51  The usability of xhypertext-based documentation may suffer from user's  Software projects manage a large base of evolving documentation, which
52  disorientation: the tendency to lose one's sense of location and  is inter-related on many levels. Design documentation gives
53  direction in a nonlinear document  architectural views on a more general level, while the program code
54  [conklin87hypertext-onpage-38-40]_. This means that users don't know  source files contain minute interface specifications and often also
55  where they are in the documentation network or how to get to some  embedded documentation giving details on how the interfaces should be
56  other place that they know to exist in the network.  used.
57    
58    .. Since these parts of documentation are semantically dependent
59       they should be interlinked together.
60    
61    There exist plenty of documentation tools to generate well navigable
62    documentations from program code source files. Altough, many of them
63    are designed to work with different programming languages, there may
64    exist conventions to use specific documentation tool with specific
65    programming language (like Javadoc with Java). When a yet another tool
66    is used to write the design documentation, linking all documentation
67    together by hand would be tedious and error-prone.
68    
69    .. - short description about problem:
70         * programming language specific tools like javadoc do generate
71           well navigable documentations from source code
72         * above them is a human written abstraction to the system
73           as whole - the design documentation
74         * how to make these documentation fragments interconnected+
75           with each other with minimum additional work
76    
77       Should be searched previous papers, which have research
78       quostions alike. Check at first the keywords given by referees
79       of UMLLink article.
80    
81    Connecting the distinct areas is essential because it could help new
82    developers in getting productive and supports development processes
83    where both design and implementation change continuously.
84    Our solution to link distinct software development documentations
85    together is to base it on UML diagrams which are drawn on design
86    documentation to abstract the system under development. We believe
87    that advantages of using UML diagrams navigational aids clearly beat
88    the minor additional work that is needed.
89    
90    .. It could be that UML diagrams won't be optimal for navigation of hypertext and
91       they won't cover the whole documentation.
92    
93  - resolving:  - resolving:
94    * connecting distinct fragments together using design    * connecting distinct fragments together using design
# Line 62  other place that they know to exist in t Line 97  other place that they know to exist in t
97    * several context views (different UML diagrams), multimenu    * several context views (different UML diagrams), multimenu
98      * spatial navigation (within the diagram)      * spatial navigation (within the diagram)
99    
100  Javadoc [friendly95javadoc]_ is a detailed and fully generated  Creation of navigational UML diagrams
101  documentation from javadoc comments of each class and method in the  =====================================
 Java source code.  
   
 Edwards and Hardman [edwards-hardman89lost-in-hyperspace]_ argue that  
 the most appropriate types of navigation devices would be based on  
 spatiality. According to their research, individuals appear to be  
 attempting to create cognitive representations of hypertext structures  
 in the form of a survey-type map. They conlude that users should be  
 allowed 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 [edwards-hardman89lost-in-hyperspace-onpage-123]_.  
102    
103  - why UML  - why UML
104    * UML is de facto standard for describing software architecture    * UML is de facto standard for describing software architecture
# Line 82  other way [edwards-hardman89lost-in-hype Line 107  other way [edwards-hardman89lost-in-hype
107    * we do not claim that UML work as the best possible diagrams    * we do not claim that UML work as the best possible diagrams
108      for documentation navigation, but it's still much better than nothing      for documentation navigation, but it's still much better than nothing
109    
110  In this article we focus on the more conventional use of UML  .. In this article we focus on the more conventional use of UML to plan
111  to plan and document software     and document software architecture on a general level.  UML can
112  architecture on a general level.     function as a common language for communication within a software
113  UML can function as a common language for     development team, and for this purpose we prefer human-drawn
114  communication within a software development team, and for this purpose     (non-autogenerated) diagrams that show the semantically meaningful
115  we prefer human-drawn (non-autogenerated) diagrams that show the semantically     features at the right level of abstraction:
116  meaningful features at the right level of abstraction:  
117    .. The usability of xhypertext-based documentation may suffer from user's
118  The distinct pieces (Javadoc and the design documentation) cannot seen as a     disorientation: the tendency to lose one's sense of location and
119  whole. The obvious question, then, is: can we increase the overall value by     direction in a nonlinear documents
120  hyperlinking the two distinct pieces of documentation?     [conklin87hypertext-onpage-38-40]_. This means that users don't know
121       where they are in the documentation network or how to get to some
122  When looking at a design document, jumping to the Javadocs to get the     other place that they know to exist in the network.
123  details would be useful, and when looking at a Javadoc, it would be  
124  most useful to be able to see if any design documents discuss that class  .. Edwards and Hardman [edwards-hardman89lost-in-hyperspace]_ argue that
125  or package.     the most appropriate types of navigation devices would be based on
126  We believe that the design documentation would be read more if     spatiality. They conlude that users should be allowed to develop a
127  made easily reachable from relevant parts of Javadoc.     cognitive map of one view of the data structure before being given the
128       opinion of navigating through the data some other way
129       [edwards-hardman89lost-in-hyperspace-onpage-123]_.
130    
131  - why UML-diagrams would work as menus  - why UML-diagrams would work as menus
132    * UMLs human made abstraction of the system containing    * UMLs human made abstraction of the system containing
# Line 116  made easily reachable from relevant part Line 143  made easily reachable from relevant part
143    * describing is fast    * describing is fast
144    * setting layout may be more    * setting layout may be more
145    
146    Embedding diagrams into HTML
147    ============================
148    
149    Javadoc [friendly95javadoc]_ is a detailed and fully generated
150    documentation from javadoc comments of each class and method in the
151    Java source code.
152    
153  - why html  - why html
154    * platform and software independent documentation    * platform and software independent documentation
155    * could be distributed in WWW, intranets etc... as it is    * could be distributed in WWW, intranets etc... as it is
# Line 134  made easily reachable from relevant part Line 168  made easily reachable from relevant part
168    * created under gzz    * created under gzz
169    * separated as navidoc    * separated as navidoc
170    
171    Usage
172    =====
173    
174  - does it really work  - does it really work
175    * WWW statistics from himalia, some comparison    * WWW statistics from himalia, some comparison
176      between pages containing UML and pages that      between pages containing UML and pages that
177      does not contain      does not contain
178    * what does the previous prove?    * what does the previous prove?
179    
180  - future  Conclusion
181    * fenfire  ==========
182    
183    .. - future
184        * fenfire
185    
186    
187    
188  .. bibliography:: gzigzag  .. bibliography:: gzigzag

Legend:
Removed from v.1.4  
changed lines
  Added in v.1.5

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