/[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.9 by tuukkah, Wed Feb 12 14:46:39 2003 UTC revision 1.10 by humppake, Wed Feb 12 17:30:21 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    
111      * generated by our UML tool from our UML diagram description language      * generated by our UML tool from our UML diagram description language
112    
113  * Cross-reference by Javadoc: cheap cross-link  * Cross-reference by Javadoc: cheap cross-link
# Line 123  Conceptual model (for HT people!) Line 124  Conceptual model (for HT people!)
124  Diagrams  Diagrams
125  ========  ========
126    
   
   
127  Introduction  Introduction
128  ============  ============
129    
130  Software projects manage a large base of evolving documentation, which is  Software projects manage a large base of evolving documentation, which
131  inter-related on many levels. Design documentation gives architectural views  is inter-related on many levels. Design documentation gives
132  on more general level, while the program code source files give all the minute  architectural views on more general level, while the program code
133  details on how the computer should act and contain embedded documentation for  source files give all the minute details on how the computer should
134  human-readability. Although these two parts of documentation are  act and contain embedded documentation for human-readability. Although
135  semantically dependent, in practice they are often linked scarcely -- if at  these two parts of documentation are semantically dependent, in
136  all.  practice they are often linked scarcely -- if at all.
137    
138  The Unified Modeling Language (UML) is the standard way to XXX visually  The Unified Modeling Language (UML) is the standard way to visually
139  describe software constructs in diagrams _[#]. It was originally developed  describe software constructs in diagrams
140  for descriptions  [booch-jacobson-rumbaugh98uml-user-guide]_. It was originally
141  on an abstract level (many constructs cannot be directly expressed in  developed for descriptions on an abstract level (many constructs
142  any programming language) _[#], but current trend is to use it also on the  cannot be directly expressed in any programming language)
143  concrete  [booch-jacobson-rumbaugh98uml-user-guide]_, but current trend is to
144  level, as to fully unify the architectural documentation and program code: the  use it also on the concrete level, as to fully unify the architectural
145  program code might be generated from highly detailed diagrams _[#], or exact  documentation and program code: the program code might be generated
146  diagrams be produced from the source code _[#].  from highly detailed diagrams
147    [harrison-barton-raghavachari00uml-to-java]_, or exact diagrams be
148    produced from the source code
149  .. [#] ``XXX`` booch-jacobson-rumbaugh-uml-user-guide?  [pierce-tilley02connecting-documentation-rose]_.
   
 .. [#] booch-jacobson-rumbaugh-uml-user-guide p.15  
        booch-jacobson-rumbaugh-uml-reference-manual p.4  
   
 .. [#] harrison-barton-raghavachari00uml-to-java  
   
 .. [#] pierce-tilley02connecting-documentation-rose  
150    
151    .. uml user guide p.XXX
152    .. uml user guide p.12
153    
154  Against this trend, we still use UML only to plan and document our software  Against this trend, we still use UML only to plan and document our software
155  architecture on general level. UML functions as a common language for  architecture on general level. UML functions as a common language for
# Line 164  prefer better abstracted and more compre Line 158  prefer better abstracted and more compre
158  human-drawn diagrams to exact illustrations matching source code to  human-drawn diagrams to exact illustrations matching source code to
159  every detail:  every detail:
160    
161      "You draw diagrams to visualize a system from different     "You draw diagrams to visualize a system from different
162      perspectives, so a diagram is a projection into a system.     perspectives, so a diagram is a projection into a system.
163      For all but the most trivial systems, a diagram represents an elided     For all but the most trivial systems, a diagram represents an elided
164      view of the elements that make up a system." [#]_     view of the elements that make up a system."
165       [booch-jacobson-rumbaugh98uml-user-guide]_
166  :   (could other stakeholders be identified and described to some extent  
167      somewhere? it might be interesting to think also towards users/customers,  .. from uml user guide p.24
168      who in some methods (ways of using XP) control use cases themselves)  
169    .. (could other stakeholders be identified and described to some
170  :   UML is easier to read than write. Also, non-programmers often don't have     extent somewhere? it might be interesting to think also towards
171      the insight needed to directly take part in designing (even in use cases)?     users/customers, who in some methods (ways of using XP) control
172       use cases themselves)
173  .. [#] booch-jacobson-rumbaugh-uml-user-guide, p.24  
174    .. UML is easier to read than write. Also, non-programmers often
175       don't have the insight needed to directly take part in designing
176  In this article, we present a navigational aid which connects the two distinct     (even in use cases)?
177  areas of documentation, and its fairly easy implementation which  
178  supplements the toolchain of other Free Software [] we use. The other  In this article, we present a navigational aid which connects the two
179  documentation tools can already generate web pages, and the tool injects the  distinct areas of documentation, and its fairly easy implementation
180  added linking to those HTML files. The tool automatically generates the  which supplements the toolchain of other Free Software
181  linking deduced from readily available UML diagram descriptions in our  [fsf02categories]_ we use. The other documentation tools can already
182  documentation. This means the tool is deployable without further authoring.  generate web pages, and the tool injects the added linking to those
183    HTML files. The tool automatically generates the linking deduced from
184  It turns out that in addition to working as multi-ended links, the diagrams  readily available UML diagram descriptions in our documentation. This
185  each generate a new navigational context within the target nodes. We found  means the tool is deployable without further authoring.
186  this useful because the Javadoc tool, which we use for program code  
187  documentation, does not promote un-hierarchical coherence.  It turns out that in addition to working as multi-ended links, the
188    diagrams each generate a new navigational context within the target
189    nodes. We found this useful because the Javadoc tool, which we use for
190    program code documentation, does not promote un-hierarchical
191    coherence.
192    
193  : Javadoc has plenty of unhierarchical links, but they are not meaningful,  ..  Javadoc has plenty of unhierarchical links, but they are not meaningful,
194    they don't give the documentation any structure.      they don't give the documentation any structure.
195    
196  : XXX move last chapter away from Introduction?  ..  XXX move last chapter away from Introduction?
197    
198  Implementation  Implementation
199  ==============  ==============
200    
201  Eventually, we found no Free Software [XXX] tools which would  Eventually, we found no Free Software [fsf02categories]_ tools which
202  fulfill our needs. Therefore, we decided to proceed with our own  would fulfill our needs. Therefore, we decided to proceed with our own
203  implementation. There were several goals to be achieved. The tool had  implementation. In addition to the previously discussed goals of the
204  to:  documentation as whole, there were also several implementation related
205    goals to be achieved. The tool had to:
206    
207  - be tidy and light-weight  - be tidy and light-weight
208    
# Line 217  to: Line 216  to:
216    
217  Up to this article all steps except the last one are implemented. The  Up to this article all steps except the last one are implemented. The
218  existing tools we selected as the basis for our documentation tool are:  existing tools we selected as the basis for our documentation tool are:
219  Javadoc [XXX], Docutils [XXX], and our own UML diagram description  Javadoc [friendly95javadoc]_, Docutils [XXX], and our own UML diagram description
220  tool. Further, the UML tool uses several free utilies to convert  tool. Further, the UML tool uses several free utilies to convert
221  each lexical UML description into final *Portable Network  each lexical UML description into final *Portable Network
222  Graphics* (PNG) diagram files. Such utilies are *MetaPost* [XXX] (mpost),  Graphics* (PNG) diagram files. Such utilies are *MetaPost* [XXX] (mpost),
# Line 225  which implements a language for picture Line 224  which implements a language for picture
224  manipulation toolkit. Besides Javadoc, all tools used are Free  manipulation toolkit. Besides Javadoc, all tools used are Free
225  Software.  Software.
226    
   
227  ??After the plugin interface is created, the documentation  ??After the plugin interface is created, the documentation
228  linking utility could also be used with other HTML documentation  linking utility could also be used with other HTML documentation
229  generators in addition to Javadoc. Though, so far, has Javadoc provided a good enough source code documentation for our purposes and we probably have no reasons to change it?  generators in addition to Javadoc. Though, so far, has Javadoc provided a good enough source code documentation for our purposes and we probably have no reasons to change it?

Legend:
Removed from v.1.9  
changed lines
  Added in v.1.10

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