/[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.67 by humppake, Sat Feb 15 15:00:21 2003 UTC revision 1.68 by tjl, Sat Feb 15 17:16:55 2003 UTC
# Line 1  Line 1 
1  ============================================================  ====================================================================
2  Bridging Javadoc and design documentation via UML image maps  Bridging Javadoc and design documentation via UML diagram image maps
3  ============================================================  ====================================================================
4    
5    
6  .. "Imagemapped UML diagrams as link nodes"  .. "Imagemapped UML diagrams as link nodes"
# Line 182  documentation bodies into focus and pres Line 182  documentation bodies into focus and pres
182  its implementation. Finally, we discuss our practical use of the tool  its implementation. Finally, we discuss our practical use of the tool
183  and conclude.  and conclude.
184    
185  Documentation in Software Engineering  Background: Documentation in Software Engineering
186  =================================================  =================================================
187    
188  Software engineering process  Software engineering process
# Line 205  software design process contains the fol Line 205  software design process contains the fol
205    up to date).    up to date).
206    
207  It should be clear that documentation plays a major role in the  It should be clear that documentation plays a major role in the
208  ideal software design process. The steps listed above should produce  ideal software design process, and that there are several different
209    types of documentation at different levels of abstraction.
210    The steps listed above should produce
211  documentation which records requirements or design decisions and  documentation which records requirements or design decisions and
212  could be used as reference manuals throughout the building of the  could be referenced throughout the building of the
213  software [brooks75mythical-man-month]_. In theory, in a Free  software [brooks75mythical-man-month]_.
214  Software project, new programmers are always free to  
215  participate independently. In practice a new programmer may need a  ..  In theory, in a Free
216        Software project, new programmers are always free to
217        participate independently.
218    
219    ..  Sometimes sufficient mentoring isn't
220        even possible, because members of a project are
221        scattered geographically.
222    
223    A programmer joining a project may need a
224  lot of mentoring by other group members before being able to contribute  lot of mentoring by other group members before being able to contribute
225  productively to the project. Sometimes sufficient mentoring isn't  productively to the project.
226  even possible, because members of a project are  This results in the Mythical Man
 scattered geographically. This results in the Mythical Man  
227  Month effect [brooks75mythical-man-month-onpage-16]_: adding a new member  Month effect [brooks75mythical-man-month-onpage-16]_: adding a new member
228  into the software design process delays rather than speeds up the  into the software design process delays rather than speeds up the
229  project.  project.
# Line 236  have to depend completely on the old sta Line 245  have to depend completely on the old sta
245  up to date and rational set of documents available for them could  up to date and rational set of documents available for them could
246  ameliorate the Mythical Man Month effect  ameliorate the Mythical Man Month effect
247  [parnas-clements86rational-onpage-255]_.  [parnas-clements86rational-onpage-255]_.
248    Improving the learning curve of new programmers may have significant effects.
249    
250  Because our group is doing experimental research with a relatively small  
251  group as an open Free Software project, we need a flexible model  ..  Because our group is doing experimental research with a relatively small
252  for software development. From the classical software      group as an open Free Software project, we need a flexible model
253  development process models, ours mostly resembles Boehm's Spiral Model      for software development. From the classical software
254  of software development and enhancement [boehm88spiral-model]_. Among      development process models, ours mostly resembles Boehm's Spiral Model
255  the modern models, Extreme Programming [beck99xp]_ is a strong influence      of software development and enhancement [boehm88spiral-model]_. Among
256  on our development process. The Spiral Model is cyclic and repetitive,      the modern models, Extreme Programming [beck99xp]_ is a strong influence
257  and every cycle has the following phases [boehm88spiral-model-onpage-64]_:      on our development process. The Spiral Model is cyclic and repetitive,
258        and every cycle has the following phases [boehm88spiral-model-onpage-64]_:
259  * analysis: determining objectives, alternatives, constraints  
260  * design: evaluating alternatives, identifying and resolving risks      * analysis: determining objectives, alternatives, constraints
261  * implementation: developing,      * design: evaluating alternatives, identifying and resolving risks
262  * test: verifying      * implementation: developing,
263  * planning next phase...      * test: verifying
264        * planning next phase...
265  When comparing Extreme Programming to the spiral model,  
266  Extreme Programming blends all phases of a single Spiral Model's      When comparing Extreme Programming to the spiral model,
267  cycle, a little at a time, throughout the entire software development      Extreme Programming blends all phases of a single Spiral Model's
268  process. The development process in Extreme Programming is      cycle, a little at a time, throughout the entire software development
269  split into smaller cycles and the analysis of the design      process. The development process in Extreme Programming is
270  objects continues throughout the design process [beck99xp]_. The      split into smaller cycles and the analysis of the design
271  Spiral Model emphasizes documenting changes before      objects continues throughout the design process [beck99xp]_. The
272  implementing them [boehm88spiral-model]_. Extreme Programming      Spiral Model emphasizes documenting changes before
273  doesn't emphasize documentation very much, relying on unit tests      implementing them [boehm88spiral-model]_. Extreme Programming
274  instead for keeping the software coherent and working [beck99xp]_.      doesn't emphasize documentation very much, relying on unit tests
275        instead for keeping the software coherent and working [beck99xp]_.
276  In our development effort, different parts of the system have  
277  different needs: the core parts of the system are frozen and      In our development effort, different parts of the system have
278  require a more formal process for changes, as in the Spiral Model.      different needs: the core parts of the system are frozen and
279  On the outer edges of the system, new research is taking place and should      require a more formal process for changes, as in the Spiral Model.
280  not be hampered by process or documentation beyond the immediate      On the outer edges of the system, new research is taking place and should
281  needs of the group members involved in the development of that particular part.      not be hampered by process or documentation beyond the immediate
282        needs of the group members involved in the development of that particular part.
283  Because of this, it is important for us that the documentation system  
284  is powerful and flexible: the core parts must have a comprehensive,      Because of this, it is important for us that the documentation system
285  easily navigable documentation but the documentation for the "edge"      is powerful and flexible: the core parts must have a comprehensive,
286  must be easy to write and maintain.      easily navigable documentation but the documentation for the "edge"
287  Thus, our documentation system should support both.      must be easy to write and maintain.
288        Thus, our documentation system should support both.
289    
290    
291  ..  The nature of our software development process affects strongly our  ..  The nature of our software development process affects strongly our
# Line 290  Thus, our documentation system should su Line 301  Thus, our documentation system should su
301      intercommunication within our group, we believe manually made human      intercommunication within our group, we believe manually made human
302      abstracted documentation serves our purposes best.      abstracted documentation serves our purposes best.
303    
304  UML  UML Diagrams
305  ---  ------------
306    
307  The Unified Modeling Language (UML) is the standard way to visually  The Unified Modeling Language (UML) is the standard way to visually
308  describe software constructs in diagrams  describe software constructs in diagrams
# Line 334  features at the right level of abstracti Line 345  features at the right level of abstracti
345  .. some references to the screenshots here?  .. some references to the screenshots here?
346    
347    
348  The problem of two separate pieces of documentation  The problem of two separate bodies of documentation
349  ===================================================  ===================================================
350    
351  In our project, as probably in most projects that use the Java programming  In our project, as probably in most projects that use the Java programming
# Line 411  article: a toolchain for bidirectional l Line 422  article: a toolchain for bidirectional l
422  documentation and Javadoc, using UML diagrams as multi-ended nexus  documentation and Javadoc, using UML diagrams as multi-ended nexus
423  links.  links.
424    
425  The design for bi-directional navigation  
426  ========================================  A design for multi-directional navigation through UML diagram imagemaps
427    =======================================================================
428    
429  Usability considerations  Usability considerations
430  ------------------------  ------------------------
# Line 514  Documentation reader's point of view Line 526  Documentation reader's point of view
526    
527  .. at least here we should also refer to the screenshots  .. at least here we should also refer to the screenshots
528    
529  Before reaching the current state, our documentation evolved through  Before reaching its current state, our documentation evolved through
530  several distinct steps, which will be viewed first from the reader's  several distinct steps, which will be viewed first from the reader's
531  and then from the developer's point of view.  and then from the developer's point of view.
532    

Legend:
Removed from v.1.67  
changed lines
  Added in v.1.68

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