161 |
|
|
162 |
.. raw:: latex |
.. raw:: latex |
163 |
|
|
164 |
\begin{figure*} |
\begin{figure*}% |
165 |
\label{example} |
\begin{centering}% |
|
\begin{centering} |
|
166 |
\includegraphics[height=9cm]{short-trav-3.gen.eps}\hskip .4cm% |
\includegraphics[height=9cm]{short-trav-3.gen.eps}\hskip .4cm% |
167 |
\includegraphics[height=9cm]{short-trav-1.gen.eps}\hskip .4cm% |
\includegraphics[height=9cm]{short-trav-1.gen.eps}\hskip .4cm% |
168 |
\includegraphics[height=9cm]{short-trav-4.gen.eps}\hskip .4cm% |
\includegraphics[height=9cm]{short-trav-4.gen.eps}\hskip .4cm% |
169 |
\end{centering} |
\end{centering}% |
170 |
\caption{Three HTML pages modified by Navidoc. |
\caption{Three HTML pages modified by Navidoc. |
171 |
The left and center pages are Javadoc pages into which the UML |
\label{example} |
172 |
diagrams have been automatically added by Navidoc at half size. |
The left and center pages are Javadocs particular interfaces and |
173 |
The right-hand page is a part of the design documentation for |
the right-hand page is a part of the design documentation for |
174 |
those interfaces. |
those interfaces, which contains a UML diagram |
175 |
The Javadoc pages are for classes which appear |
on which the two interfaces described by the Javadoc pages appear. |
|
in the UML diagram on the design documentation page. |
|
176 |
Reduced copies of this diagram have been added to both Javadoc pages. |
Reduced copies of this diagram have been added to both Javadoc pages. |
177 |
The elements in the diagram are active: clicking on the Scrollblock |
The elements in the diagrams are active: clicking on the Scrollblock |
178 |
element in any of the diagrams takes the user to the Scrollblock |
element in any of the diagrams takes the user to the Scrollblock |
179 |
javadoc page. |
javadoc. |
180 |
Traversing |
Traversing |
181 |
to the design document works by clicking the heading at the |
to the design document works by clicking the heading at the |
182 |
top of the diagram. |
top of the diagram. |
183 |
In each version of the diagram, the element corresponding to |
In each version of the UML diagram, |
184 |
the currently active node is highlighted both with color |
the currently active node is highlighted both with color |
185 |
and a distinctive thick, irregular line to catch the viewer's eye. |
and a distinctive thick, irregular line to catch the viewer's eye. |
186 |
} |
}% |
187 |
\end{figure*} |
\end{figure*} |
188 |
|
|
189 |
.. The diagram works as |
.. The diagram works as |
384 |
Experiences |
Experiences |
385 |
=========== |
=========== |
386 |
|
|
387 |
Statistics from our project's WWW server show that diagrams |
Statistics from the WWW server of our project show that the |
388 |
|
UML diagrams |
389 |
have been used to traverse between javadoc and design documentation. |
have been used to traverse between javadoc and design documentation. |
390 |
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 |
391 |
design documentation page request came by traversing from javadoc to |
design documentation page request came by traversing from javadoc to |
392 |
design documentation via diagrams. Further, 11% of all |
design documentation via diagrams. Further, 11% of all |
393 |
javadoc visits came from design documentation using imagemapped |
javadoc visits came from design documentation using imagemapped |
394 |
diagrams. |
diagrams. |
|
|
|
395 |
Unfortunately, the referrer logs did not allow us to |
Unfortunately, the referrer logs did not allow us to |
396 |
identify the use of UML diagrams for navigation |
identify the use of UML diagrams for navigation |
397 |
within javadoc pages or within design documents, because those groups |
within javadoc pages or within design documents, because there |
398 |
have other links as well. We expect those number |
are other links besides the UML diagrams between those pages. |
399 |
would be even higher. |
|
400 |
|
|
401 |
|
.. We expect those number would be even higher. |
402 |
|
|
403 |
.. Anecdotally XXX |
.. Anecdotally XXX |
404 |
|
|
419 |
Conclusion |
Conclusion |
420 |
========== |
========== |
421 |
|
|
422 |
We have presented a navigational aid, which hypertexturally connects |
We have presented a navigational aid which hypertexturally connects |
423 |
two distinct areas of documentation, using human-authored UML diagrams |
two distinct areas of documentation using human-authored UML diagrams |
424 |
as spatial menus. |
as spatial menus. |
425 |
It is not a new idea to use UML diagrams in documentation |
Now, it is not a new idea to use UML diagrams as spatial menus --- |
426 |
navigation. For example, Doxygen [heesch03doxygen]_ automatically |
for example, Doxygen [heesch03doxygen]_ automatically |
427 |
generates class |
generates class |
428 |
inheritance trees for navigation within the embedded documentation. |
inheritance trees for navigation within the embedded documentation. |
429 |
Design documentation has been connected to |
Also, there has been |
430 |
program code as well, through textual analysis [maletic03recovering]_. |
work on connecting design documentation to code |
431 |
|
as well, e.g. through textual analysis [maletic03recovering]_. |
432 |
However, automatically generated diagrams and indices often include |
However, automatically generated diagrams and indices often include |
433 |
too much irrelevant information; human-made UML diagrams are quite different |
too much irrelevant information; human-made UML diagrams are quite different |
434 |
from automatically generated ones since they try to *express* a part of |
from automatically generated ones since they try to *express* a meaningful |
435 |
|
part of |
436 |
the system's semantics. |
the system's semantics. |
437 |
|
What is |
438 |
New in our approach is the use of UML diagrams from the design |
new in our approach is the use of human-made UML diagrams from the design |
439 |
documentation and their insertion to the relevant Javadoc or other embedded |
documentation as spatial menus |
440 |
documentation pages as spatial menus, allowing traversal between the design |
on the relevant Javadoc or other embedded |
441 |
documentation and the Javadoc pages. |
documentation pages, allowing traversal between the design |
442 |
|
documentation and the Javadoc pages as well as giving the user an |
443 |
|
idea of the context of the current class. |
444 |
|
|
445 |
.. Of course, generated documentation may give well detailed information |
.. Of course, generated documentation may give well detailed information |
446 |
from the current implementation, but the design documentation should |
from the current implementation, but the design documentation should |