/[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.62 by tjl, Sat Feb 15 13:47:03 2003 UTC revision 1.63 by tjl, Sat Feb 15 13:58:42 2003 UTC
# Line 141  Abstract Line 141  Abstract
141      Our simple implementation as a Free Software toolchain is in daily use      Our simple implementation as a Free Software toolchain is in daily use
142      in our project.      in our project.
143    
144  In this article, we present a navigational aid for software engineering documentation.  We present a navigational aid for software engineering documentation.
145  Based on using UML diagrams as multi-ended links, the tool connects two  Based on using UML diagrams as multi-ended links, we hypertexturally
146    connect two
147  distinct areas of software engineering documentation: architectural documents and javadoc.  distinct areas of software engineering documentation: architectural documents and javadoc.
148    
149  and its lightweight implementation  and its lightweight implementation
# Line 166  them by hand is tedious and error-prone Line 167  them by hand is tedious and error-prone
167  software.  software.
168    
169  In this article, we present a navigational aid for software engineering documentation.  In this article, we present a navigational aid for software engineering documentation.
170  Based on using UML diagrams as multi-ended links, the tool connects two  Based on using UML diagrams as multi-ended links, our tool connects two
171  distinct areas of software engineering documentation: architectural documents and javadoc.  distinct areas of software engineering documentation: architectural documents and javadoc.
172    
173  .. XXX This means the software was deployable without further authoring.  .. XXX This means the software was deployable without further authoring.
# Line 214  productively to the project. Sometimes s Line 215  productively to the project. Sometimes s
215  even possible, because members of a project are  even possible, because members of a project are
216  scattered geographically. This results in the Mythical Man  scattered geographically. This results in the Mythical Man
217  Month effect [brooks75mythical-man-month-onpage-16]_: adding a new member  Month effect [brooks75mythical-man-month-onpage-16]_: adding a new member
218  into the software design process delays than speeds up the  into the software design process delays rather than speeds up the
219  project.  project.
220    
221    "Men and months are interchangeable commodities only when a task can be    "Men and months are interchangeable commodities only when a task can be
# Line 227  project. Line 228  project.
228    the plan of work.--- ---Intercommunication is worse."    the plan of work.--- ---Intercommunication is worse."
229    [brooks75mythical-man-month-onpage-18]_    [brooks75mythical-man-month-onpage-18]_
230    
231  Eventually, the greater the amount of programmers or the higher the  Obviously, the greater the amount of programmers or the higher the
232  turnover rate, the more important it is to have good  turnover rate, the more important it is to have good
233  documentation.  When new programmers join the project they shouldn't  documentation.  When new programmers join the project they shouldn't
234  have to depend completely on the old staff for finding their way around. An  have to depend completely on the old staff for finding their way around. An
# Line 235  up to date and rational set of documents Line 236  up to date and rational set of documents
236  ameliorate the Mythical Man Month effect  ameliorate the Mythical Man Month effect
237  [parnas-clements86rational-onpage-255]_.  [parnas-clements86rational-onpage-255]_.
238    
239  Because our group is doing experimental research with a rather small  Because our group is doing experimental research with a relatively small
240  group and as an open Free Software project, we need a flexible model  group as an open Free Software project, we need a flexible model
241  for software development. From the classical software  for software development. From the classical software
242  development process models, ours mostly resembles Boehm's Spiral Model  development process models, ours mostly resembles Boehm's Spiral Model
243  of software development and enhancement [boehm88spiral-model]_. Among  of software development and enhancement [boehm88spiral-model]_. Among
# Line 254  When comparing Extreme Programming to th Line 255  When comparing Extreme Programming to th
255  Extreme Programming blends all phases of a single Spiral Model's  Extreme Programming blends all phases of a single Spiral Model's
256  cycle, a little at a time, throughout the entire software development  cycle, a little at a time, throughout the entire software development
257  process. The development process in Extreme Programming is  process. The development process in Extreme Programming is
258  splitted into even smaller cycles and the analysis of the design  split into smaller cycles and the analysis of the design
259  objects continues throughout the design process [beck99xp]_. The  objects continues throughout the design process [beck99xp]_. The
260  Spiral Model emphasizes documenting changes before  Spiral Model emphasizes documenting changes before
261  implementing them [boehm88spiral-model]_. Extreme Programming  implementing them [boehm88spiral-model]_. Extreme Programming
262  doesn't emphasize documentation very much, relying on unit tests  doesn't emphasize documentation very much, relying on unit tests
263  instead for keeping the software coherent and working [beck99xp]_.  instead for keeping the software coherent and working [beck99xp]_.
264    
265  The nature of our software development process affects strongly our  In our development effort, different parts of the system have
266  documentation needs. As we proceed by prototyping and enhancing our  different needs: the core parts of the system are frozen and
267  software step by step, also our documentation should be updated in  require a more formal process for changes, as in the Spiral Model.
268  every cycle. Athough, the detailed implementation is in continual  On the outer edges of the system, new research is taking place and should
269  change, and we prefer to emphasis the more constant and general design  not be hampered by process or documentation beyond the immediate
270  documentation. Of course, more detailed up to date documentation could  needs of the group members.
271  be generated from the current source for those members who are working  
272  with particular details. Though, in more general design documentation  Because of this, it is important for us that the documentation system
273  rapidly changing details would be irrelevant and confusing. Since  is powerful and flexible: the core parts must have a comprehensive,
274  currently the main purpose for our documentation is to help  easily navigable documentation but the documentation for the "edge"
275  intercommunication within our group, we believe manually made human  must be easy to write and maintain.
276  abstracted documentation serves our purposes best.  Thus, our documentation system should support both.
277    
278    
279    ..  The nature of our software development process affects strongly our
280        documentation needs. As we proceed by prototyping and enhancing our
281        software step by step, our documentation should also be updated in
282        every cycle. Athough, the detailed implementation is in continual
283        change, and we prefer to emphasis the more constant and general design
284        documentation. Of course, more detailed up to date documentation could
285        be generated from the current source for those members who are working
286        with particular details. Though, in more general design documentation
287        rapidly changing details would be irrelevant and confusing. Since
288        currently the main purpose for our documentation is to help
289        intercommunication within our group, we believe manually made human
290        abstracted documentation serves our purposes best.
291    
292  UML  UML
293  ---  ---

Legend:
Removed from v.1.62  
changed lines
  Added in v.1.63

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