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 |
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 |
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 |
|
|
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 |
--------------------------------------- |
--------------------------------------- |