129 |
its implementation. Finally, we discuss our practical use of the tool |
its implementation. Finally, we discuss our practical use of the tool |
130 |
and conclude. |
and conclude. |
131 |
|
|
132 |
Background: Documentation in Software Engineering |
Background |
133 |
================================================= |
========== |
134 |
|
|
135 |
Software engineering process |
Software engineering process |
136 |
---------------------------- |
---------------------------- |
266 |
intercommunication within our group, we believe manually made human |
intercommunication within our group, we believe manually made human |
267 |
abstracted documentation serves our purposes best. |
abstracted documentation serves our purposes best. |
268 |
|
|
269 |
UML Diagrams |
UML diagrams |
270 |
------------ |
------------ |
271 |
|
|
272 |
The Unified Modeling Language (UML) is the standard way to |
The Unified Modeling Language (UML) is the standard way to |
311 |
.. some references to the screenshots here? |
.. some references to the screenshots here? |
312 |
|
|
313 |
|
|
314 |
The problem of two separate bodies of documentation |
Setting of problem |
315 |
=================================================== |
================== |
316 |
|
|
317 |
In our software engineering project [gzz]_, as probably in most projects that use the Java programming |
In our software engineering project [gzz]_, as probably in most projects that use the Java programming |
318 |
language [java-ref]_, the software development documentation is |
language [java-ref]_, the software development documentation is |
399 |
links. |
links. |
400 |
|
|
401 |
|
|
402 |
A design for multi-directional navigation through UML diagram imagemaps |
Structure design |
403 |
======================================================================= |
================ |
404 |
|
|
405 |
Usability considerations |
Usability considerations |
406 |
------------------------ |
------------------------ |
444 |
|
|
445 |
To see which possibilities we have when linking from diagrams, we use |
To see which possibilities we have when linking from diagrams, we use |
446 |
Cook and Daniels's classification of UML diagrams into three classes |
Cook and Daniels's classification of UML diagrams into three classes |
447 |
[cook-daniels-94-oo-modelling]_: conceptual diagrams, specification |
[cook-daniels94-oo-modelling]_: conceptual diagrams, specification |
448 |
diagrams and implementation diagrams. Looking into the items available in |
diagrams and implementation diagrams. Looking into the items available in |
449 |
each of these classes, we come to the conclusion shown in Table [linking-ref]_. |
each of these classes, we come to the conclusion shown in Table [ref-linking]_. |
450 |
|
|
451 |
.. figure:: table |
.. figure:: table |
452 |
:environment: table |
:environment: table |
496 |
Semantic meanings of traversing the bi-directional links of a diagram. |
Semantic meanings of traversing the bi-directional links of a diagram. |
497 |
Curves mean linkage by spatial relation. |
Curves mean linkage by spatial relation. |
498 |
|
|
499 |
Documentation reader's point of view |
Reader's point of view |
500 |
--------------------------------------- |
--------------------------------------- |
501 |
|
|
502 |
.. at least here we should also refer to the screenshots |
.. at least here we should also refer to the screenshots |
555 |
.. Advantage over paper: MAJOR: multi-end links easily traversable, |
.. Advantage over paper: MAJOR: multi-end links easily traversable, |
556 |
structure can be understood |
structure can be understood |
557 |
|
|
558 |
Documentation developer's point of view |
Authors's point of view |
559 |
----------------------------------------- |
----------------------------------------- |
560 |
|
|
561 |
On the developer side, creating diagrams within the design |
On the developer side, creating diagrams within the design |
682 |
a description of all the elements in diagram [ref-umltoolumlsourcelinked]_ |
a description of all the elements in diagram [ref-umltoolumlsourcelinked]_ |
683 |
and description their graphical layout [ref-umltoolmpsource]_. The |
and description their graphical layout [ref-umltoolmpsource]_. The |
684 |
final diagram [ref-umltoolexample]_ is compiled |
final diagram [ref-umltoolexample]_ is compiled |
685 |
|
|
686 |
[ref-umltoolconvert]_ from the element and layout descriptions. The |
[ref-umltoolconvert]_ from the element and layout descriptions. The |
687 |
description of existing elements is easily done using our UML tools' |
description of existing elements is easily done using our UML tools' |
688 |
lexical description language and the description is readable even |
lexical description language and the description is readable even |
854 |
The two distinct phases of generating Javadoc and design |
The two distinct phases of generating Javadoc and design |
855 |
documentation bridged via UML diagrams. |
documentation bridged via UML diagrams. |
856 |
|
|
857 |
Practical use |
Experiences |
858 |
============= |
=========== |
859 |
|
|
860 |
The UML and linking tools are currently in everyday use in the Gzz |
The UML and linking tools are currently in everyday use in the Gzz |
861 |
project [gzz]_. For now, the documentation covers about 380 Java classes |
project [gzz]_. For now, the documentation covers about 380 Java classes |
961 |
=============== |
=============== |
962 |
|
|
963 |
The authors would like to thank Toni Alatalo for discussions regarding |
The authors would like to thank Toni Alatalo for discussions regarding |
964 |
this manuscript and Benja Fallenstein for discussions, proofreading, |
this manuscript and Benja Fallenstein for discussions and proofreading, |
965 |
and participation in implementing the software. |
and participation in implementing the software. |
966 |
|
|
967 |
.. bibliography:: gzigzag |
.. bibliography:: gzigzag |