/[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.35 by tjl, Wed Jan 22 21:11:28 2003 UTC revision 1.36 by tjl, Thu Jan 23 07:41:13 2003 UTC
# Line 166  doc++ a free software alternative for ja Line 166  doc++ a free software alternative for ja
166  Setting of problem  Setting of problem
167  ==================  ==================
168    
169  In our project, ...,  In our project, as probably in most projects that use Java,
170  the software engineering documentation  the software engineering (not user!) documentation is divided into two classes:
171  is divided into two classes:  design documentation and Javadoc.
172    
173  Javadoc  The design documents cover the most important architectural features
174    and are written either before coding (for design) or after (for exposition
175   - fully generated documentation from javadoc comments  of the architecture).
    of each class and method in the java source code  
   
    + the javadoc output filestructure follows the  
      hierarchical tree structure of java packages and classes  
   
 Architectural docs with UML diagrams:  
   
   
   
176    
177   - diagrams are from human to human   - diagrams are from human to human
178    
# Line 190  Architectural docs with UML diagrams: Line 181  Architectural docs with UML diagrams:
181     + generated diagrams are too detailed to be beneficial     + generated diagrams are too detailed to be beneficial
182     + basic architectural diagrams should be done before code anyway     + basic architectural diagrams should be done before code anyway
183    
   
         
   
   
184     + and if design documentation is outdated some particular classes     + and if design documentation is outdated some particular classes
185       maybe don't even exist anymore!       maybe don't even exist anymore!
186    
  - these cover the most relevant parts from the architecture  
    and the code  
187    
188   - Include PEGs: possibly not-yet accepted or not-yet implemented proposals   - Include PEGs: possibly not-yet accepted or not-yet implemented proposals
189     for architectural changes.     for architectural changes.
190    
191    Javadoc, on the other hand, is
192    
193     - fully generated documentation from javadoc comments
194       of each class and method in the java source code
195    
196       + the javadoc output filestructure follows the
197         hierarchical tree structure of java packages and classes
198    
199    
200          
201    
202    
203    
204  The two types of documentation are complementary, as demonstrated in the following table..  
205    
206    The two types of documentation are complementary, as demonstrated in the following table:
207    
208  +----------------------------------------+----------------------------------------------+  +----------------------------------------+----------------------------------------------+
209  |       Design docs                      |           Javadoc                            |  |       Design docs                      |           Javadoc                            |
# Line 227  The two types of documentation are compl Line 226  The two types of documentation are compl
226  | - written and organized by humans      |                                              |  | - written and organized by humans      |                                              |
227  |                                        |                                              |  |                                        |                                              |
228  +----------------------------------------+----------------------------------------------+  +----------------------------------------+----------------------------------------------+
 "Obvious" question: can we increase the overall value by  
 interconnecting the two?  
229    
230  Architectural docs easily left in the dark reaches of the filesystem,  Problems with the docs:
 not used as often as javadocs.  
231    
232   + hypertext disorientation problem still exists   +  Architectural docs easily left in the dark reaches of the filesystem,
233        not used as often as javadocs. - refs about documents left unused because
234        hard to find?
235    
236     + hypertext disorientation problem still exists with javadoc
237    
238     Edwards, D., & Hardman, L. (1989). Lost in Hyperspace:     Edwards, D., & Hardman, L. (1989). Lost in Hyperspace:
239     Cognitive Mapping and Navigation in a Hypertext Environment.     Cognitive Mapping and Navigation in a Hypertext Environment.
# Line 242  not used as often as javadocs. Line 242  not used as often as javadocs.
242     (code in JYU-lib: "MK TIE HYPER")     (code in JYU-lib: "MK TIE HYPER")
243    
244    
245    "Obvious" question: can we increase the overall value by
246    interconnecting the two?
247    
248  Design  Design
249  ======  ======
250    

Legend:
Removed from v.1.35  
changed lines
  Added in v.1.36

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