/[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.26 by humppake, Fri Feb 14 16:37:35 2003 UTC revision 1.27 by tuukkah, Fri Feb 14 16:38:45 2003 UTC
# Line 122  Bridging Javadoc to design documentation Line 122  Bridging Javadoc to design documentation
122     * (XXX Free Software vs. Open Source vs. Open Software vs. Open Project...)     * (XXX Free Software vs. Open Source vs. Open Software vs. Open Project...)
123    
124    
125  .. Diagrams  Keywords
126     ========  =======
127    
128    * web
129    * user interfaces
130    * spatial menus
131    
132    
133    
134  Introduction  Introduction
135  ============  ============
136    
137  Software projects manage a large base of evolving documentation, which  Software projects manage a large base of evolving documentation, which
138  is inter-related on many levels. Design documentation gives  is inter-related on many levels. Design documentation gives
139  architectural views on more general level, while the program code  architectural views on a more general level, while the program code
140  source files give all the minute details on how the computer should  source files give all the minute details on how the computer should
141  act and contain embedded documentation for human-readability. Although  act and contain embedded documentation for human-readability. Although
142  these two parts of documentation are semantically dependent, in  these two parts of documentation are semantically dependent, linking
143  practice they are often linked scarcely -- if at all.  them is tedious -- if even possible -- when they are authored using different
144    software.
145    
146  The Unified Modeling Language (UML) is the standard way to visually  The Unified Modeling Language (UML) is the standard way to visually
147  describe software constructs in diagrams  describe software constructs in diagrams
# Line 150  produced from the source code Line 157  produced from the source code
157  [pierce-tilley02connecting-documentation-rose]_.  [pierce-tilley02connecting-documentation-rose]_.
158    
159  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
160  architecture on general level. UML functions as a common language for  architecture on a general level. UML functions as a common language for
161  communication within our software development team, and in this purpose we  communication within our software development team, and in this purpose we
162  prefer better abstracted and more comprehensible  prefer better abstracted and more comprehensible
163  human-drawn diagrams to exact illustrations matching source code to  human-drawn diagrams to exact illustrations matching source code to
# Line 175  In this article, we present a navigation Line 182  In this article, we present a navigation
182  distinct areas of documentation, and its fairly easy implementation  distinct areas of documentation, and its fairly easy implementation
183  which supplements the toolchain of other Free Software  which supplements the toolchain of other Free Software
184  [fsf02categories]_ we use. The other documentation tools can already  [fsf02categories]_ we use. The other documentation tools can already
185  generate web pages, and the tool injects the added linking to those  generate web pages, and the new software injects the added linking to those
186  HTML files. The tool automatically generates the linking deduced from  HTML files. The software automatically generates the linking deduced from
187  readily available UML diagram descriptions in our documentation. This  readily available UML diagram descriptions in our documentation. This
188  means the tool is deployable without further authoring.  means the software was deployable without further authoring.
189    
190  It turns out that in addition to working as multi-ended links, the  Earlier, concept-based navigation and map-based navigation have added
191  diagrams each generate a new navigational context within the target  horizontal links on top of hierarchical hypertext [brusilovsky02-mapnav]_.
192  nodes. We found this useful because the Javadoc tool, which we use for  The structure we discuss in this paper is similar as the diagram becomes a
193  program code documentation, does not promote un-hierarchical  navigational node, but we don't rely on keywords or heuristics in link
194  coherence.  creation.
195    
196    Further, as the diagram is shown inside a web page, it functions as
197    a multi-target link.
198    
199    We limit the enhancement to web pages generated during the documentation build
200    process, which makes the task of our software easier than that of other web
201    augmentation tools [weinreich00-linkvis]_.
202    
203  ..  Javadoc has plenty of unhierarchical links, but they are not meaningful,  ..  Javadoc has plenty of unhierarchical links, but they are not meaningful,
204      they don't give the documentation any structure.      they don't give the documentation any structure.
205    
 ..  XXX move last chapter away from Introduction?  
   
206  Background  Background
207  ==========  ==========
208    
# Line 428  design documentation and to javadoc as f Line 440  design documentation and to javadoc as f
440     :alternative: *     :alternative: *
441     :label: diagramlinks     :label: diagramlinks
442    
443     Semantic meanings of traversing the bi-directional links of a diagram     Semantic meanings of traversing the bi-directional links of a diagram.
444       Curves mean linkage by spatial relation.
445    
446  Documentation reader's point of view  Documentation reader's point of view
447  ---------------------------------------  ---------------------------------------

Legend:
Removed from v.1.26  
changed lines
  Added in v.1.27

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