74 |
the source code usually contains |
the source code usually contains |
75 |
embedded documentation, such as Javadoc [friendly95javadoc]_, giving details on the concrete |
embedded documentation, such as Javadoc [friendly95javadoc]_, giving details on the concrete |
76 |
classes and methods. |
classes and methods. |
|
|
|
|
.. Since these parts of documentation are semantically dependent |
|
|
they should be interlinked together. |
|
|
|
|
77 |
The generation of easily navigable hypertext |
The generation of easily navigable hypertext |
78 |
from the embedded documentation is essentially |
from the embedded documentation is essentially |
79 |
a solved problem |
a solved problem |
100 |
the javadoc is not terribly useful: it lacks the information |
the javadoc is not terribly useful: it lacks the information |
101 |
on how to create objects that implement this interface. |
on how to create objects that implement this interface. |
102 |
The only relevant links are on an accompanying ``Use`` page, |
The only relevant links are on an accompanying ``Use`` page, |
103 |
which lists all the references to this interface in any method |
without any context: the methods for |
|
prototypes elsewhere in the |
|
|
documentation. |
|
|
The list does not give information about the contextual importance of |
|
|
the items --- the methods for |
|
104 |
creating a ``PublicKey`` are listed alongside the accessor methods |
creating a ``PublicKey`` are listed alongside the accessor methods |
105 |
that return a ``PublicKey`` contained in another, unrelated object. |
that return a ``PublicKey`` contained in another, unrelated object. |
106 |
|
|
107 |
|
.. at ``http://java.sun.com/j2se/1.4.1/docs/api/java/security/PublicKey.html``. |
108 |
|
|
109 |
Far more helpful would be a link to the design |
Far more helpful would be a link to the design |
110 |
documentation, even just a diagram showing the intended |
documentation, even just a diagram showing the intended |
111 |
uses or lifespans of related objects and how one creates the objects. |
uses or lifespans of related objects and how one creates the objects. |
112 |
These architectural diagrams certainly exist for all properly managed |
These architectural diagrams are |
113 |
|
certain to *already exist* for all properly managed |
114 |
medium-to-large scale software projects --- the problem is getting |
medium-to-large scale software projects --- the problem is getting |
115 |
them to where it matters without having to manually insert |
them to where it matters without having to manually insert |
116 |
the links into the low-level documentation. |
the links into the low-level documentation. |
|
|
|
|
.. at ``http://java.sun.com/j2se/1.4.1/docs/api/java/security/PublicKey.html``. |
|
|
|
|
117 |
In this article, we introduce Navidoc: a system that, given design |
In this article, we introduce Navidoc: a system that, given design |
118 |
documentation with marked-up UML diagrams, inserts the UML |
documentation with marked-up UML diagrams, inserts the UML |
119 |
diagrams into the classes' javadocs to function as spatial menus. |
diagrams into the classes' javadocs to function as spatial menus. |
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 |
Some screenshots illustrating this navigation paradigm are shown |
Some screenshots illustrating this navigation paradigm are shown |
220 |
in Figure [ref-example]_. |
in Figure [ref-example]_. |
221 |
|
|
280 |
.. think, this should be much clearer :) But how to say everything shortly... |
.. think, this should be much clearer :) But how to say everything shortly... |
281 |
|
|
282 |
Navidoc, our implementation, is a light-weight tool built on top of |
Navidoc, our implementation, is a light-weight tool built on top of |
283 |
existing Free Software tools. Its main function is to |
existing Free Software tools. |
|
compile |
|
|
the design documentation and the UML diagrams embedded within it |
|
|
and to insert copies of the UML diagrams into the embedded documentation |
|
|
pages. |
|
284 |
Navidoc converts each |
Navidoc converts each |
285 |
UML diagram into a set of imagemaps --- one |
UML diagram into a set of imagemaps --- one |
286 |
for each target document since the current document is highlighted |
for each target document since the current document is highlighted |
287 |
in the images. The diagrams allow easy traversal |
in the images and inserts them into the relevant documents. |
288 |
through all the participant nodes, and also contain a backlink to the design document page |
The diagrams allow easy traversal |
289 |
|
through all the participant nodes, |
290 |
|
and also contain a backlink to the design document page |
291 |
containing the original diagram. |
containing the original diagram. |
292 |
The automatically inserted images |
The automatically inserted images |
293 |
are scaled to half size to avoid cluttering the Javadoc pages. |
are scaled to half size to avoid cluttering the Javadoc pages. |
294 |
|
|
295 |
|
.. Its main function is to |
296 |
|
compile |
297 |
|
the design documentation and the UML diagrams embedded within it |
298 |
|
and to insert copies of the UML diagrams into the embedded documentation |
299 |
|
pages. |
300 |
|
|
301 |
|
|
302 |
.. After compiling, it creates imagemaps for every UML diagram to link |
.. After compiling, it creates imagemaps for every UML diagram to link |
303 |
diagrams' elements to corresponding source code documentation |
diagrams' elements to corresponding source code documentation |
334 |
|
|
335 |
* setting layout may be more |
* setting layout may be more |
336 |
|
|
337 |
We have found it useful to create UML diagrams using textual syntax |
.. We have found it useful to create UML diagrams using textual syntax |
338 |
embedded into the design documentation source --- it is easier for programmers, |
embedded into the design documentation source --- it is easier for programmers, |
339 |
and our tools allows the separation of the structure and layout of the diagram. |
and our tools allows the separation of the structure and layout of the diagram. |
340 |
However, with minor modifications, Navidoc should also be usable |
However, with minor modifications, Navidoc should also be usable |
341 |
when using direct manipulation GUIs to create the UML diagrams. |
when using direct manipulation GUIs to create the UML diagrams. |
342 |
|
|
343 |
.. In software |
.. In software |
344 |
development groups, where programmers also write the documentation, |
development groups, where programmers also write the documentation, |
395 |
Experiences |
Experiences |
396 |
=========== |
=========== |
397 |
|
|
398 |
|
We have found navidoc useful in our free software project family, |
399 |
|
the most important aspect being the value added to the Javadoc pages. |
400 |
|
Anecdotally, reaching the right documentation and understanding the context |
401 |
|
and interrelations between classes is easier. |
402 |
|
|
403 |
Statistics from the WWW server of our project show that the |
Statistics from the WWW server of our project show that the |
404 |
UML diagrams |
UML diagrams |
405 |
have been used to traverse between javadoc and design documentation. |
have been used to traverse between javadoc and design documentation (approx. 10% |
406 |
During three months (Jan 03 till end of Mar 03), 9% of all |
of traversals). |
|
design documentation page requests resulted from traversing from the Javadoc pages to |
|
|
design documentation via UML diagrams, and 11% of all |
|
|
Javadoc page requests resulted from traversing from design documentation to the Javadoc pages |
|
|
using the imagemapped |
|
|
diagrams. |
|
407 |
Unfortunately, the referrer logs did not allow us to |
Unfortunately, the referrer logs did not allow us to |
408 |
identify the use of UML diagrams for navigation |
identify the use of UML diagrams for navigation |
409 |
within javadoc pages or within design documents, because there |
within javadoc pages or within design documents, because there |
410 |
are other links besides the UML diagrams between those pages. |
are other links besides the UML diagrams between those pages --- |
411 |
|
this is a serious problem since anecdotally the UML diagrams are used to traverse |
412 |
|
between Javadoc pages more often than to design documentation: a common |
413 |
|
navigation technique appears to be to flick quickly between the Javadoc pages |
414 |
|
and then possibly read the deeper data in the design documentation. |
415 |
|
|
416 |
|
|
417 |
Also, we are unable to say how much of the traffic came from testing |
Also, we are unable to say how much of the traffic came from testing |
418 |
and debugging Navidoc itself and how much from real use. |
and debugging Navidoc itself and how much from real use. |
419 |
Anecdotally, finding the context *is* easier with the UML diagrams. |
|
420 |
|
.. During three months (Jan 03 till end of Mar 03), 9% of all |
421 |
|
design documentation page requests resulted from traversing from the Javadoc pages to |
422 |
|
design documentation via UML diagrams, and 11% of all |
423 |
|
Javadoc page requests resulted from traversing from design documentation to the Javadoc pages |
424 |
|
using the imagemapped |
425 |
|
diagrams. |
426 |
|
|
427 |
|
|
428 |
.. We expect those number would be even higher. |
.. We expect those number would be even higher. |
470 |
documentation and the Javadoc pages as well as giving the user an |
documentation and the Javadoc pages as well as giving the user an |
471 |
idea of the context of the current class. |
idea of the context of the current class. |
472 |
|
|
473 |
So far in our experience Navidoc has proven to be a most useful tool; |
.. So far, Navidoc has proven to be a most useful tool; |
474 |
not only for improving the Javadoc navigability but also giving the design |
not only for improving the Javadoc navigability but also giving the design |
475 |
documentation writer an added incentive to create UML diagrams. |
documentation writer an added incentive to create UML diagrams. |
476 |
|
|
477 |
.. Of course, generated documentation may give well detailed information |
.. Of course, generated documentation may give well detailed information |
478 |
from the current implementation, but the design documentation should |
from the current implementation, but the design documentation should |