162 |
.. raw:: latex |
.. raw:: latex |
163 |
|
|
164 |
\begin{figure*} |
\begin{figure*} |
165 |
|
\label{example} |
166 |
\begin{centering} |
\begin{centering} |
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% |
261 |
|
|
262 |
.. think, this should be much clearer :) But how to say everything shortly... |
.. think, this should be much clearer :) But how to say everything shortly... |
263 |
|
|
264 |
Navidoc, our implementation, is as a light-weight tool built on top of |
Navidoc, our implementation, is a light-weight tool built on top of |
265 |
several existing Free Software tools. Its main purpose is to compile |
several existing Free Software tools. Its main purpose is to compile |
266 |
the design documentation and UML diagrams embedded within it. |
the design documentation and UML diagrams embedded within it. |
267 |
Navidoc uses several free utilies to convert each |
Navidoc uses several free utilies to convert each |
268 |
textual UML diagram description into a set of imagemaps --- one |
textual UML diagram description into a set of imagemaps --- one |
269 |
for each target document since the current document is highlighted |
for each target document since the current document is highlighted |
270 |
in the images. These diagrams embedded into target documents, allow easy traverse |
in the images. These diagrams embedded into target documents, allow easy traverse |
271 |
through all the participant nodes and backlink to the startup page holding |
through all the participant nodes and backlink to the startup page, which |
272 |
the original diagram. |
contains the original diagram. |
273 |
The automatically inserted images |
The automatically inserted images |
274 |
are scaled to half size, whereas in their "real" location |
are scaled to half size, whereas in their "real" location |
275 |
in the design documentation the images are shown at their full size. |
in the design documentation the images are shown at their full size. |
309 |
|
|
310 |
* setting layout may be more |
* setting layout may be more |
311 |
|
|
312 |
We've it found useful to create UML diagrams using textual syntax |
We have found it useful to create UML diagrams using textual syntax |
313 |
embedded within documentation page originals. In small softaware |
embedded within documentation page originals. In small softaware |
314 |
development groups, where programmers also write the documentation, |
development groups, where programmers also write the documentation, |
315 |
the documentation tools shouldn't be gap to change the programming |
switching programming tool to documentation tools should not be a |
316 |
tool to document writing tools. Textual UML diagram description, of |
barrier to write documentation and clarify it with diagrams. Textual |
317 |
course, can be written with any text editor. Comparing with any direct |
UML diagram description, of course, can be written with any text |
318 |
manipulation drawing tool, textual description may feel abstract at |
editor. Comparing with direct manipulation drawing tools, textual |
319 |
first, but the when users are programmers it could be even more |
description may feel a bit abstract, but for programmers it |
320 |
natural for them to describe things lexically. |
could be very natural to describe things lexically. |
321 |
|
|
322 |
.. Also at least for a |
.. Also at least for a |
323 |
programmer, who are used to describe objects lexically, describing |
programmer, who are used to describe objects lexically, describing |
361 |
Experiences |
Experiences |
362 |
=========== |
=========== |
363 |
|
|
364 |
The statistics of our projects WWW server show that diagrams |
The statistics of our project's WWW server show that diagrams |
365 |
connecting javadoc to design documentationg have increased the usage |
connecting javadoc to design documentationg have significantly |
366 |
of project's design documentation and traversing between documentation |
increased the usage of project's design documentation and traversing |
367 |
levels is very common. In the period of three months (Jan 03 till end |
between documentation levels. Altough, we couldn't distuinguish usage |
368 |
of Mar 03) at least 9% of all design documentation page request came |
of design documentation's or javadoc's internal navigation from usage |
369 |
by traversing from javadoc to design documentation via diagrams. On |
of imagemapped diagrams, we could track the usage of diagrams, when |
370 |
the other hand at least 11% of all javadoc visits came from design |
browsing between design documentation and javadoc. |
371 |
documentation via diagrams. |
|
372 |
|
In the period of three months (Jan 03 till end of Mar 03) 9% of all |
373 |
|
design documentation page request came by traversing from javadoc to |
374 |
|
design documentation via diagrams. On the other hand 11% of all |
375 |
|
javadoc visits came from design documentation using imagemapped |
376 |
|
diagrams. |
377 |
|
|
378 |
|
.. , how much usage of UML diagrams |
379 |
|
as spatial menus replace usage of documentation's internal navigation. |
380 |
|
|
381 |
|
|
382 |
.. * WWW statistics from himalia: 2003/01 - 2003/03 |
.. * WWW statistics from himalia: 2003/01 - 2003/03 |
383 |
|
|
392 |
Conclusion |
Conclusion |
393 |
========== |
========== |
394 |
|
|
395 |
|
We have presented a navigational aid, which hypertexturally connects |
396 |
|
two distinct areas of documentation, using human-authored UML diagrams |
397 |
|
as spatial menus. |
398 |
|
|
399 |
It is not a new idea to use UML diagrams in documentation |
It is not a new idea to use UML diagrams in documentation |
400 |
navigation. There already exists Javadoc like documentation generation |
navigation. There already exists Javadoc like documentation generation |
401 |
tools, which generate automaticly classdiagrams from program source |
tools, which generate automaticly class diagrams from program source |
402 |
code to help navigation in generated documentation. |
code to help navigation inside the generated documentation. |
403 |
Doxygen [heesch03doxygen]_, |
[heesch03doxygen]_, for example, generates diagrams of class |
|
for example, generates diagrams of class |
|
404 |
inheritance tree for that purpose. |
inheritance tree for that purpose. |
405 |
|
|
406 |
|
Our approach is different, since we prefer fully human created |
407 |
|
diagrams in our design documentation. We want to avoid being bloated |
408 |
|
by a large amount of too detailed diagrams, which are often resulted |
409 |
|
by generators interpreting only the source code. On the other hand, |
410 |
|
recently there has been promising work based on textual analysis of |
411 |
|
connectable documentations [maletic03recovering]_. XXX need for the |
412 |
|
last sentence :). |
413 |
|
|
414 |
|
.. Of course, generated documentation may give well detailed information |
415 |
|
from the current implementation, but the design documentation should |
416 |
|
also cover the future and be rather well abstracted than well |
417 |
|
detailed. Therefore, we want to avoid being bloated by a large amount |
418 |
|
of too detailed diagrams (meanless for us) and prefer fully human |
419 |
|
created diagrams in our design documentation. |
420 |
|
|
421 |
|
|
422 |
|
.. Our approach is different from most tools, |
423 |
|
which rely more on automatically generated links [maletic03recovering]_, |
424 |
|
or inserting connections to the source code [devanbu99chime]_. |
425 |
|
|
426 |
|
|
427 |
|
|
428 |
.. - other analysis software |
.. - other analysis software |
429 |
|
|
430 |
.. - autogen not comparable to design doc |
.. - autogen not comparable to design doc |
431 |
|
|
|
Of course, generated documentation may give well detailed information |
|
|
from the current implementation, but the design documentation should |
|
|
also cover the future and be rather well abstracted than well |
|
|
detailed. Therefore, we want to avoid being bloated by a large amount |
|
|
of too detailed diagrams (meanless for us) and prefer fully human |
|
|
created diagrams in our design documentation. |
|
432 |
|
|
433 |
.. - how are UMLs embedded into documentation |
.. - how are UMLs embedded into documentation |
434 |
|
|
|
Our approach is different from most tools, |
|
|
which rely more on automatically generated links [maletic03recovering]_, |
|
|
or inserting connections to the source code [devanbu99chime]_. |
|
435 |
|
|
436 |
.. - future |
.. - future |
437 |
* fenfire |
* fenfire |