/[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.43 by benja, Sat Feb 15 09:57:44 2003 UTC revision 1.44 by benja, Sat Feb 15 10:13:23 2003 UTC
# Line 137  Abstract Line 137  Abstract
137  ========  ========
138    
139  We describe automatic linking of design documentation to javadoc  We describe automatic linking of design documentation to javadoc
140  through UML diagrams embedded in both, acting as nexus links.  through UML diagrams embedded in both, acting as multi-target nexus links.
141    Our simple implementation as a Free Software toolchain is in daily use
142    in our project.
143    
144  XXX !!!  XXX !!!
145    
# Line 191  In this article, we present a navigation Line 193  In this article, we present a navigation
193  distinct areas of documentation, and its fairly easy implementation  distinct areas of documentation, and its fairly easy implementation
194  which supplements the toolchain of other Free Software  which supplements the toolchain of other Free Software
195  [fsf02categories]_ we use. The other documentation tools can already  [fsf02categories]_ we use. The other documentation tools can already
196  generate web pages, and the new software injects the added linking to those  generate web pages, and our new software injects the added linking to those
197  HTML files. The software automatically generates the linking deduced from  HTML files. The software automatically generates the linking deduced from
198  readily available UML diagram descriptions in our documentation. This  readily available UML diagram descriptions in our documentation. This
199  means the software was deployable without further authoring.  means the software was deployable without further authoring.
# Line 211  augmentation tools [weinreich00-linkvis] Line 213  augmentation tools [weinreich00-linkvis]
213    
214  The current implementation is a part of and in use at our Free  The current implementation is a part of and in use at our Free
215  Software project [gzz]_, where it generates the publicly web-browsable  Software project [gzz]_, where it generates the publicly web-browsable
216  hypertext [gzz_doc_himalia]_ of project's documentation, as a part of  hypertext [gzz_doc_himalia]_ of the project's documentation, as a part of
217  the toolchain.  the toolchain.
218    
219  ..  Javadoc has plenty of unhierarchical links, but they are not meaningful,  ..  Javadoc has plenty of unhierarchical links, but they are not meaningful,
# Line 227  results could be achieved by faking "the Line 229  results could be achieved by faking "the
229  software design process contains the following steps  software design process contains the following steps
230  [parnas-clements86rational-onpage-252-255]_:  [parnas-clements86rational-onpage-252-255]_:
231    
232    - establish and document requirements  - establish and document requirements
233    - design and document the module structure  - design and document the module structure
234    - design and document the module interfaces  - design and document the module interfaces
235    - design and document the uses hierarchy  - design and document the uses hierarchy
236    - design and document the module internal structures  - design and document the module internal structures
237    - write programs  - write programs
238    - maintain (redesign and redevelopment, keeping documentation  - maintain (redesign and redevelopment, keeping documentation
239      up to date).    up to date).
240    
241  It should be clear that documentation plays major role in the  It should be clear that documentation plays a major role in the
242  ideal software design process. Steps listed above should produce  ideal software design process. The steps listed above should produce
243  documentation, which records requirements or design decisions and  documentation which records requirements or design decisions and
244  could be used as reference manuals throughout the building of the  could be used as reference manuals throughout the building of the
245  software [brooks75mythical-man-month]_. In theory, in a Free  software [brooks75mythical-man-month]_. In theory, in a Free
246  Software [fsf02categories]_ project new programmers are always free to  Software project, new programmers are always free to
247  participate independently. In practice a new programmer could need a  participate independently. In practice a new programmer may need a
248  lot of mentoring by other group members, before one could be  lot of mentoring by other group members before being able to contribute
249  productive for the project. Sometimes sufficient mentoring could not  productively to the project. Sometimes sufficient mentoring isn't
250  even be possible, because members of such a projects could be  even possible, because members of a project are
251  geographically widely scattered. This results in the Mythical Man  scattered geographically. This results in the Mythical Man
252  Month effect [brooks75mythical-man-month-onpage-16]_: adding a new member  Month effect [brooks75mythical-man-month-onpage-16]_: adding a new member
253  into software design process could rather delay than speed up the  into the software design process delays than speeds up the
254  project.  project.
255    
256    "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 261  project. Line 263  project.
263    the plan of work.-- --Intercommunication is worse."    the plan of work.-- --Intercommunication is worse."
264    [brooks75mythical-man-month-onpage-18]_    [brooks75mythical-man-month-onpage-18]_
265    
266  Eventually, the greater is the amount of programmers or higher the  Eventually, the greater the amount of programmers or the higher the
267  turnover within them, the more important it is to have a good  turnover rate, the more important it is to have good
268  documentation.  When new programmers join the project they shouldn't  documentation.  When new programmers join the project they shouldn't
269  have to depend completely on the old staff for their information. An  have to depend completely on the old staff for finding their way around. An
270  up to date and rational set of documents available for them could  up to date and rational set of documents available for them could
271  ameliorate the Mythical Man Month effect  ameliorate the Mythical Man Month effect
272  [parnas-clements86rational-onpage-255]_.  [parnas-clements86rational-onpage-255]_.
273    
274  Because our group is doing experimental research with a rather small  Because our group is doing experimental research with a rather small
275  group and as an open Free Software project, we need a flexible model  group and as an open Free Software project, we need a flexible model
276  for software development process. From the classical software  for software development. From the classical software
277  development process models, ours reminds most of Boehm's Spiral Model  development process models, ours mostly resembles Boehm's Spiral Model
278  of software development and enhancement [boehm88spiral-model]_. From  of software development and enhancement [boehm88spiral-model]_. Among
279  the modern models our development process is influenced by Extreme  the modern models, Extreme Programming [beck99xp]_ is a strong influence
280  Programming [beck99xp]_. The Spiral Model is cyclic and repetitive,  on our development process. The Spiral Model is cyclic and repetitive,
281  and every cycle has the following phases [boehm88spiral-model-onpage-64]_:  and every cycle has the following phases [boehm88spiral-model-onpage-64]_:
282    
283   * analysis: determining objectives, alternatives, constraints  * analysis: determining objectives, alternatives, constraints
284   * design: evaluating alternatives, identifying and resolving risks  * design: evaluating alternatives, identifying and resolving risks
285   * implementation: developing,  * implementation: developing,
286   * test: verifying  * test: verifying
287   * planning next phase...  * planning next phase...
288    
289  When comparing the Extreme Programming to the spiral model, the  When comparing Extreme Programming to the spiral model,
290  Extreme Programming blends all phases of a single Spiral Model's  Extreme Programming blends all phases of a single Spiral Model's
291  cycle, a little at a time, throughout the entire software development  cycle, a little at a time, throughout the entire software development
292  process.a single development cycle is even shorter than in the spriral  process. The development process in Extreme Programming is
 model. Though, the development process in Extreme Programming is  
293  splitted into even smaller cycles and the analysis of the design  splitted into even smaller cycles and the analysis of the design
294  objects continues throughout the design process. [beck99xp]_ The  objects continues throughout the design process [beck99xp]_. The
295  Spiral Model emphasizes a lot documenting the changes before  Spiral Model emphasizes documenting changes before
296  implementing them [boehm88spiral-model]_. The Extreme Programming  implementing them [boehm88spiral-model]_. Extreme Programming
297  don't speak out much about documentation, but relies on unit tests  doesn't emphasize documentation very much, relying on unit tests
298  keeping the software coherent and working [beck99xp]_.  instead for keeping the software coherent and working [beck99xp]_.
299    
300  The nature of our software development process affects strongly our  The nature of our software development process affects strongly our
301  documentation needs. As we proceed by prototyping and enhancing our  documentation needs. As we proceed by prototyping and enhancing our

Legend:
Removed from v.1.43  
changed lines
  Added in v.1.44

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