210 |
a single program element often appears on several separate diagrams |
a single program element often appears on several separate diagrams |
211 |
that |
that |
212 |
together create a multicontext view for the element. |
together create a multicontext view for the element. |
213 |
|
Using the UML diagrams created for the design documentation |
214 |
Using UML diagrams as spatial menus to jump around |
as spatial menus to jump around |
215 |
the documents for the different program elements |
the documents for the different program elements |
216 |
is attractive exactly because of this: each diagram |
is attractive exactly because of this: each diagram |
217 |
in which an element appears gives some of the necessary |
in which an element appears gives some of the necessary |
218 |
context for that element. |
context for that element. |
219 |
Since the diagrams also appear in the design documentation, |
|
220 |
which is definitely related to the program elements |
Some screenshots illustrating this navigation paradigm are shown |
221 |
described in the diagram, it should also be reachable |
in Figure [ref-example]_. |
222 |
through the spatial menu in the diagram --- we insert |
|
223 |
into the diagrams some elements that show where |
.. Since the diagrams also appear in the design documentation, |
224 |
the diagram appears in the design documentation. |
which is definitely related to the program elements |
225 |
Figure 1 [ref-example]_ shows some example HTML pages produced by our system. |
described in the diagram, it should also be reachable |
226 |
|
through the spatial menu in the diagram --- we insert |
227 |
|
into the diagrams some elements that show where |
228 |
|
the diagram appears in the design documentation. |
229 |
|
Figure 1 [ref-example]_ shows some example HTML pages produced by our system. |
230 |
|
|
231 |
|
|
232 |
.. Because UML diagrams should be made anyway, it is good start to |
.. Because UML diagrams should be made anyway, it is good start to |
283 |
.. think, this should be much clearer :) But how to say everything shortly... |
.. think, this should be much clearer :) But how to say everything shortly... |
284 |
|
|
285 |
Navidoc, our implementation, is a light-weight tool built on top of |
Navidoc, our implementation, is a light-weight tool built on top of |
286 |
several existing Free Software tools. Its main purpose is to compile |
several existing Free Software tools. Its main function is to |
287 |
the design documentation and UML diagrams embedded within it. |
compile |
288 |
|
the design documentation and UML diagrams embedded within it |
289 |
|
and to insert copies of the UML diagrams into the embedded documentation |
290 |
|
pages. |
291 |
Navidoc uses several free utilies to convert each |
Navidoc uses several free utilies to convert each |
292 |
textual UML diagram description into a set of imagemaps --- one |
UML diagram into a set of imagemaps --- one |
293 |
for each target document since the current document is highlighted |
for each target document since the current document is highlighted |
294 |
in the images. These diagrams, embedded into target documents, allow easy traversal |
in the images. The diagrams allow easy traversal |
295 |
through all the participant nodes, and they backlink to the startup page, which |
through all the participant nodes, and also contain a backlink to the design document page |
296 |
contains the original diagram. |
containing the original diagram. |
297 |
The automatically inserted images |
The automatically inserted images |
298 |
are scaled to half size, whereas in the original location |
are scaled to half size to avoid cluttering the Javadoc pages. |
299 |
in the design documentation the images are shown at their full size. |
|
300 |
|
|
301 |
.. After compiling, it creates imagemaps for every UML diagram to link |
.. After compiling, it creates imagemaps for every UML diagram to link |
302 |
diagrams' elements to corresponding source code documentation |
diagrams' elements to corresponding source code documentation |
334 |
* setting layout may be more |
* setting layout may be more |
335 |
|
|
336 |
We have found it useful to create UML diagrams using textual syntax |
We have found it useful to create UML diagrams using textual syntax |
337 |
embedded within documentation page originals. In software |
embedded into the design documentation source --- it is easier for programmers |
338 |
development groups, where programmers also write the documentation, |
and our tools allows the separation of the structure and layout of the diagram. |
|
the switch from programming tools to documentation tools should |
|
|
not be a barrier to writing documentation and clarifying it with diagrams. |
|
339 |
However, with minor modifications, Navidoc should also be usable |
However, with minor modifications, Navidoc should also be usable |
340 |
when using direct manipulation GUIs to create the UML diagrams. |
when using direct manipulation GUIs to create the UML diagrams. |
341 |
|
|
342 |
|
.. In software |
343 |
|
development groups, where programmers also write the documentation, |
344 |
|
the switch from programming tools to documentation tools should |
345 |
|
not be a barrier to writing documentation and clarifying it with diagrams. |
346 |
|
|
347 |
.. Compared to direct manipulation drawing tools, textual |
.. Compared to direct manipulation drawing tools, textual |
348 |
description may feel abstract, but describing things lexically is natural |
description may feel abstract, but describing things lexically is natural |
349 |
to programmers. |
to programmers. |
398 |
UML diagrams |
UML diagrams |
399 |
have been used to traverse between javadoc and design documentation. |
have been used to traverse between javadoc and design documentation. |
400 |
During three months (Jan 03 till end of Mar 03), 9% of all |
During three months (Jan 03 till end of Mar 03), 9% of all |
401 |
design documentation page request came by traversing from javadoc to |
design documentation page requests resulted from traversing from the Javadoc pages to |
402 |
design documentation via diagrams. Further, 11% of all |
design documentation via UML diagrams, and 11% of all |
403 |
javadoc visits came from design documentation using imagemapped |
Javadoc page requests resulted from traversing from design documentation to the Javadoc pages |
404 |
|
using the imagemapped |
405 |
diagrams. |
diagrams. |
406 |
Unfortunately, the referrer logs did not allow us to |
Unfortunately, the referrer logs did not allow us to |
407 |
identify the use of UML diagrams for navigation |
identify the use of UML diagrams for navigation |
408 |
within javadoc pages or within design documents, because there |
within javadoc pages or within design documents, because there |
409 |
are other links besides the UML diagrams between those pages. |
are other links besides the UML diagrams between those pages. |
410 |
|
Also, we are unable to say how much of the traffic came from testing |
411 |
|
and debugging Navidoc itself and how much from real use. |
412 |
|
Anecdotally, finding the context *is* easier with the UML diagrams. |
413 |
|
|
414 |
|
|
415 |
.. We expect those number would be even higher. |
.. We expect those number would be even higher. |
433 |
Conclusion |
Conclusion |
434 |
========== |
========== |
435 |
|
|
436 |
We have presented a navigational aid which hypertexturally connects |
We have presented a navigational aid which hypertextually connects |
437 |
two distinct areas of documentation using human-authored UML diagrams |
two distinct areas of documentation using human-authored UML diagrams |
438 |
as spatial menus. |
as spatial menus. |
439 |
Now, it is not a new idea to use UML diagrams as spatial menus --- |
Now, it is not a new idea to use UML diagrams as spatial menus --- |
443 |
Also, there has been |
Also, there has been |
444 |
work on connecting design documentation to code |
work on connecting design documentation to code |
445 |
as well, e.g. through textual analysis [maletic03recovering]_. |
as well, e.g. through textual analysis [maletic03recovering]_. |
446 |
|
|
447 |
|
|
448 |
However, automatically generated diagrams and indices often include |
However, automatically generated diagrams and indices often include |
449 |
too much irrelevant information; human-made UML diagrams are quite different |
too much irrelevant information; human-made UML diagrams are quite different |
450 |
from automatically generated ones since they try to *express* a meaningful |
from automatically generated ones since they try to *express* a meaningful |