/[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.68 by tjl, Sat Feb 15 17:16:55 2003 UTC revision 1.69 by tjl, Sat Feb 15 17:34:57 2003 UTC
# Line 304  Improving the learning curve of new prog Line 304  Improving the learning curve of new prog
304  UML Diagrams  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
308  describe software constructs in diagrams  visually
309    describe software architectures and constructs in diagrams
310  [booch-jacobson-rumbaugh98uml-user-guide]_. It was originally  [booch-jacobson-rumbaugh98uml-user-guide]_. It was originally
311  developed for descriptions on an abstract level (many constructs  developed for descriptions on an abstract level (many constructs
312  cannot be directly expressed in any programming language)  cannot be directly expressed in any programming language)
# Line 348  features at the right level of abstracti Line 349  features at the right level of abstracti
349  The problem of two separate bodies of documentation  The problem of two separate bodies of documentation
350  ===================================================  ===================================================
351    
352  In our project, as probably in most projects that use the Java programming  In our software engineering project[gzz]_, as probably in most projects that use the Java programming
353  language [java-ref]_, the software development documentation is  language [java-ref]_, the software development documentation is
354  divided into two separate domains: the design documentation and  divided into two major domains: the design documentation and
355  Javadoc [friendly95javadoc]_. The design documents cover the most  Javadoc [friendly95javadoc]_. The design documents cover the most
356  important architectural features and are written either before coding  important architectural features and are written either before coding
357  (for design) or after (for exposition or of the architecture or refactoring design).  (for design) or after (for exposition or of the architecture or refactoring design).
# Line 402  During coding, the Javadoc documentation Line 403  During coding, the Javadoc documentation
403  necessary, but the design documentation is easily left in the  necessary, but the design documentation is easily left in the
404  dark reaches of the filesystem. It could be argued that the reason for  dark reaches of the filesystem. It could be argued that the reason for
405  design documents being left unused is that relevant parts linked to  design documents being left unused is that relevant parts linked to
406  ongoing work are hard to find. The distinct pieces (Javadoc and the  ongoing work are hard to find.
407  design documentation) cannot seen as a whole. Therefore we should make  
408  them work better as a whole.  For example, when referring to the Javadoc on how to use some API,
409    one often comes across an interface which is of the type that
410    one would like to obtain from somewhere, but unless someone
411    has explicitly written the instructions into the doc comments,
412    the Javadoc will only explain how the interface is used.
413    What is exasperates this situation is the certainty
414    that in the architectural document, there surely is a diagram and a section
415    which talks about the issue but finding them will take time.
416    
417    The distinct pieces (Javadoc and the
418    design documentation) cannot seen as a whole.
419    
420  The obvious question, then, is: can we increase the overall value by hyperlinking the  The obvious question, then, is: can we increase the overall value by hyperlinking the
421  two distinct pieces of documentation?  two distinct pieces of documentation?

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

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