/[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.6 by tuukkah, Wed Feb 12 07:51:41 2003 UTC revision 1.7 by tuukkah, Wed Feb 12 09:59:09 2003 UTC
# Line 107  Conceptual model (for HT people!) Line 107  Conceptual model (for HT people!)
107  * UML diagrams: distinct context for Java classes and packages and relevant  * UML diagrams: distinct context for Java classes and packages and relevant
108    architectural documentation; spatial menu; also node (XXX multi-ended nexus    architectural documentation; spatial menu; also node (XXX multi-ended nexus
109    links)    links)
110          * generated by our UML tool from our UML diagram description language        * generated by our UML tool from our UML diagram description language
111    
112  * Cross-reference by Javadoc: cheap cross-link  * Cross-reference by Javadoc: cheap cross-link
113  * Cross-link from javadoc comments: simple hyperlink  * Cross-link from javadoc comments: simple hyperlink
# Line 115  Conceptual model (for HT people!) Line 115  Conceptual model (for HT people!)
115    (poorly implemented as WWW)    (poorly implemented as WWW)
116    
117  * Links in UML diagrams: context navigation links  * Links in UML diagrams: context navigation links
118          * generated by our UML link tool without any extra information      * generated by our UML link tool without any extra information
119    
120  * (XXX Free Software vs. Open Source vs. Open Software vs. Open Project...)  * (XXX Free Software vs. Open Source vs. Open Software vs. Open Project...)
121    
122    
123    Introduction
124    ============
125    
126    Software projects manage a large base of evolving documentation, which is
127    inter-related on many levels. Design documentation gives architectural views
128    on more general level, while the program code source files give all the minute
129    details on how the computer should act and contain embedded documentation for
130    human-readability. Although these two parts of documentation are
131    semantically dependent, in praftice they are often linked scarcely -- if at
132    all.
133    
134    The Unified Modeling Language (UML) is the standard way to visually describe
135    software constructs in diagrams. It was originally developed for descriptions
136    on an abstract level (many constructs cannot be directly expressed in
137    any programming language), but current trend is to use it also on the concrete
138    level, as to fully unify the architectural documentation and program code: the
139    program code might be generated from highly detailed diagrams, or exact
140    diagrams be produced from the source code.
141    
142    Against this trend, we still use UML only to plan and document our software
143    architecture on general level. UML functions as a common language for
144    communication within our software development team, and in this purpose we
145    prefer better abstracted and more comprehensible
146    human-drawn diagrams to exact illustrations matching source code to
147    every detail:
148    
149        "You draw diagrams to visualize a system from different
150        perspectives, so a diagram is a projection into a system.
151        For all but the most trivial systems, a diagram represents an elided
152        view of the elements that make up a system." [#]_
153    
154    :   (could other stakeholders be identified and described to some extent
155        somewhere? it might be interesting to think also towards users/customers,
156        who in some methods (ways of using XP) control use cases themselves)
157    
158    :   UML is easier to read than write. Also, non-programmers often don't have
159        the insight needed to directly take part in designing (even in use cases)?
160    
161    .. [#] booch-jacobson-rumbaugh-uml-user-guide, p.24
162    
163    
164    In this article, we present a navigational tool which connects the two distinct
165    areas of documentation, and the fairly simple tool implementation which
166    supplements the toolchain of other Free Software [] we use. The other
167    documentation tools can already generate web pages, and the tool injects the
168    added linking to those HTML files. The tool automatically generates the
169    linking deduced from readily available UML diagram descriptions in our
170    documentation. This means the tool is deployable without further authoring.
171    
172    It turns out that in addition to working as multi-ended links, the diagrams
173    each generate a new navigational context within the target nodes. We found
174    this useful because the Javadoc tool, which we use for program code
175    documentation, does not promote un-hierarchical coherence.
176    
177    : Javadoc has plenty of unhierarchical links, but they are not meaningful,
178      they don't give the documentation any structure.
179    
180    : XXX move last chapter away from Introduction?
181    
182  Implementation  Implementation
183  ==============  ==============
184    

Legend:
Removed from v.1.6  
changed lines
  Added in v.1.7

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