/[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.57 by tjl, Sat Feb 15 13:02:50 2003 UTC revision 1.58 by tjl, Sat Feb 15 13:06:11 2003 UTC
# Line 182  augmentation tools [weinreich00-linkvis] Line 182  augmentation tools [weinreich00-linkvis]
182  ..  Javadoc has plenty of unhierarchical links, but they are not meaningful,  ..  Javadoc has plenty of unhierarchical links, but they are not meaningful,
183      they don't give the documentation any structure.      they don't give the documentation any structure.
184    
185  The role of documentation in Software Engineering  In the following sections, we first discuss the role of documentation
186    in software engineering, then bring the problem of the distinct
187    documentation bodies into focus and present our solution and
188    its implementation. Finally, we discuss our practical use of the tool
189    and conclude.
190    
191    Documentation in Software Engineering
192  =================================================  =================================================
193    
194    Software engineering process
195    ----------------------------
196    
197  In their article "A rational design process: how and why to fake it"  In their article "A rational design process: how and why to fake it"
198  [parnas-clements86rational]_ Parnas and Clements argue that rational  [parnas-clements86rational]_ Parnas and Clements argue that rational
199  software design process is not generally possible, but acceptable  software design process is not generally possible, but acceptable
# Line 273  currently the main purpose for our docum Line 282  currently the main purpose for our docum
282  intercommunication within our group, we believe manually made human  intercommunication within our group, we believe manually made human
283  abstracted documentation serves our purposes best.  abstracted documentation serves our purposes best.
284    
285    UML
286    ---
287    
288    The Unified Modeling Language (UML) is the standard way to visually
289    describe software constructs in diagrams
290    [booch-jacobson-rumbaugh98uml-user-guide]_. It was originally
291    developed for descriptions on an abstract level (many constructs
292    cannot be directly expressed in any programming language)
293    [booch-jacobson-rumbaugh98uml-user-guide-onpage-12]_, but the current
294    trend in research is to use it also on the concrete level, as to fully unify the
295    architectural documentation and program code: the program code might
296    be generated from highly detailed diagrams
297    [harrison-barton-raghavachari00uml-to-java]_.
298    Another use of UML is in reverse engineering, where
299    diagrams may be produced from the source code
300    [pierce-tilley02connecting-documentation-rose]_.
301    
302    In this article we focus on the more conventional use of UML
303    to plan and document software
304    architecture on a general level.
305    UML can function as a common language for
306    communication within a software development team, and for this purpose
307    human-drawn (non-autogenerated) diagrams show the semantically meaningful
308    features at the right level of abstraction are preferred:
309    
310       "You draw diagrams to visualize a system from different
311       perspectives, so a diagram is a projection into a system.
312       For all but the most trivial systems, a diagram represents an elided
313       view of the elements that make up a system."
314       [booch-jacobson-rumbaugh98uml-user-guide-onpage-24]_
315    
316    .. (could other stakeholders be identified and described to some
317       extent somewhere? it might be interesting to think also towards
318       users/customers, who in some methods (ways of using XP) control
319       use cases themselves)
320    
321    .. UML is easier to read than write. Also, non-programmers often
322       don't have the insight needed to directly take part in designing
323       (even in use cases)?
324    
325    
326    .. some references to the screenshots here?
327    
328    
329  The problem of two separate pieces of documentation  The problem of two separate pieces of documentation
330  ===================================================  ===================================================
331    
# Line 361  links. Line 414  links.
414    
415  The design for bi-directional navigation  The design for bi-directional navigation
416  ========================================  ========================================
   
 UML  
 ---  
   
 The Unified Modeling Language (UML) is the standard way to visually  
 describe software constructs in diagrams  
 [booch-jacobson-rumbaugh98uml-user-guide]_. It was originally  
 developed for descriptions on an abstract level (many constructs  
 cannot be directly expressed in any programming language)  
 [booch-jacobson-rumbaugh98uml-user-guide-onpage-12]_, but the current  
 trend in research is to use it also on the concrete level, as to fully unify the  
 architectural documentation and program code: the program code might  
 be generated from highly detailed diagrams  
 [harrison-barton-raghavachari00uml-to-java]_.  
 Another use of UML is in reverse engineering, where  
 diagrams may be produced from the source code  
 [pierce-tilley02connecting-documentation-rose]_.  
   
 In this article we focus on the more conventional use of UML  
 to plan and document software  
 architecture on a general level.  
 UML can function as a common language for  
 communication within a software development team, and for this purpose  
 human-drawn (non-autogenerated) diagrams show the semantically meaningful  
 features at the right level of abstraction are preferred:  
   
    "You draw diagrams to visualize a system from different  
    perspectives, so a diagram is a projection into a system.  
    For all but the most trivial systems, a diagram represents an elided  
    view of the elements that make up a system."  
    [booch-jacobson-rumbaugh98uml-user-guide-onpage-24]_  
   
 .. (could other stakeholders be identified and described to some  
    extent somewhere? it might be interesting to think also towards  
    users/customers, who in some methods (ways of using XP) control  
    use cases themselves)  
   
 .. UML is easier to read than write. Also, non-programmers often  
    don't have the insight needed to directly take part in designing  
    (even in use cases)?  
   
   
 .. some references to the screenshots here?  
   
417  XXX Hypertext blaablaa something...  XXX Hypertext blaablaa something...
418  -----------------------------------  -----------------------------------
419    

Legend:
Removed from v.1.57  
changed lines
  Added in v.1.58

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