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