/[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.33 by tjl, Wed Jan 22 18:17:15 2003 UTC revision 1.34 by tjl, Wed Jan 22 21:07:44 2003 UTC
# Line 12  Issues Line 12  Issues
12    OTOH, talking more about us makes it more personal but may make it    OTOH, talking more about us makes it more personal but may make it
13    also seem less relevant to others' efforts.    also seem less relevant to others' efforts.
14    
15        SUGGESTED RESOLUTION: "Setting of problem" should be about us:
16        describe exactly what docs **we** have. Everything else
17        should be more general, and we should point out that
18        this situation is probably not uncommon.
19    
20  - do we need critics against graphical coding with UML somewhere?  - do we need critics against graphical coding with UML somewhere?
21    This could be found at least in articles supporting    This could be found at least in articles supporting
22    domain spesific languages (which may be used for graphical coding)    domain spesific languages (which may be used for graphical coding)
23    
24        RESOLVED: Probably not: graphical languages have not taken
25        off to a sufficient degree that we should really have to criticize
26        them.
27    
28    - How should we discuss WYSIWYG, WYSIAYG for reST &c? Someone will surely ask about that,
29    
30        PARTIAL RESOLUTION:
31    
32            - proprietarity
33            - versioning much worse
34            - users = programmers --> used to editing text and compiling
35            - lack of good, **extensible** tools
36    
37    - why even outdated but well simplified diagram
38      is better than too detailed, automaticly up-to dated
39      and reverse engineered diagram.
40    
41    
42  Introduction  Introduction
43  ============  ============
44    
# Line 143  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  Javadoc  In our project, ...,
170    the software engineering documentation
171    is divided into two classes:
172    
173   - fully generated documentation from development  The two types of documentation are complementary.
    project's java source code  
174    
175   - easy to find a given class, easy to check methods  +----------------------------------------+----------------------------------------------+
176    |       Design docs                      |           Javadoc                            |
177    +----------------------------------------+----------------------------------------------+
178    |                                        |                                              |
179    | - good overall picture.                |  - easy to find a given class,               |
180    |                                        |    easy to check all methods                 |
181    |                                        |                                              |
182    | - little detail,                       |  - detailed                                  |
183    |                                        |                                              |
184    | - may be slightly outdated at          |  - methods and classes *always* up to        |
185    |   any particular time.                 |    date (generated from source),             |
186    |                                        |    doc comments also usually                 |
187    |                                        |                                              |
188    | - hard to find explanations            |  - no overall picture of classes' roles      |
189    |   for a particular class.              |                                              |
190    |                                        |                                              |
191    | - UML diagrams                         |                                              |
192    |                                        |                                              |
193    | - written and organized by humans      |                                              |
194    |                                        |                                              |
195    +----------------------------------------+----------------------------------------------+
196    
197    Javadoc
198    
199     - fully generated documentation from javadoc comments
200       of each class and method in the java source code
201    
202     + the javadoc output filestructure follows the     + the javadoc output filestructure follows the
203       hierarchical tree structure of java packages and classes       hierarchical tree structure of java packages and classes
204    
205   - the location in class-tree is well shown everywhere in   + hypertext disorientation problem still exists
    javadoc, but the role of single class or package in  
    developing software remains unknown  
   
    + hard to get overall picture.  
    + hypertext disorientation problem still exists  
206    
207     Edwards, D., & Hardman, L. (1989). Lost in Hyperspace:     Edwards, D., & Hardman, L. (1989). Lost in Hyperspace:
208     Cognitive Mapping and Navigation in a Hypertext Environment.     Cognitive Mapping and Navigation in a Hypertext Environment.
# Line 166  Javadoc Line 210  Javadoc
210     Practice (105-125), Oxford: Intellect Limited.     Practice (105-125), Oxford: Intellect Limited.
211     (code in JYU-lib: "MK TIE HYPER")     (code in JYU-lib: "MK TIE HYPER")
212    
  - because doc is generated from source, the class, method, field  
    names and their inline documentation are always up-to-date(!!)  
213    
214  Architectural docs with UML diagrams:  Architectural docs with UML diagrams:
215    
216    
217    
218    
219   - diagrams are from human to human   - diagrams are from human to human
220    
221     + we don't wan to generate diagrams from the code or generate     + we don't wan to generate diagrams from the code or generate
# Line 178  Architectural docs with UML diagrams: Line 223  Architectural docs with UML diagrams:
223     + generated diagrams are too detailed to be beneficial     + generated diagrams are too detailed to be beneficial
224     + basic architectural diagrams should be done before code anyway     + basic architectural diagrams should be done before code anyway
225    
  - good overall picture.  
226    
  - little detail,  
   
  - may be slightly outdated at any particular time.  
227                
    + why even outdated but well simplified diagram  
      is better than too detailed, automaticly up-to dated  
      and reverse engineered diagram.  
228    
  - distinct from the javadoc, hard to find explanations  
    for a particular class.  
229    
230     + and if documentation is outdated some particular classes     + and if design documentation is outdated some particular classes
231       maybe don't even exist anymore!       maybe don't even exist anymore!
232    
233   - these cover the most relevant parts from the architecture   - these cover the most relevant parts from the architecture
234     and the code     and the code
235    
236  The two types of documentation are complementary.   - Include PEGs: possibly not-yet accepted or not-yet implemented proposals
237       for architectural changes.
238    
239  "Obvious" question: can we increase the overall value by  "Obvious" question: can we increase the overall value by
240  interconnecting the two?  interconnecting the two?

Legend:
Removed from v.1.33  
changed lines
  Added in v.1.34

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