77 |
the design documentation and the embedded documentation. |
the design documentation and the embedded documentation. |
78 |
This can be daunting to a newcomer; consider the javadoc |
This can be daunting to a newcomer; consider the javadoc |
79 |
for the interface ``java.security.PublicKey`` in Sun's |
for the interface ``java.security.PublicKey`` in Sun's |
80 |
Java2 SDK 1.4.1 at |
Java2 SDK 1.4.1 |
81 |
``http://java.sun.com/j2se/1.4.1/docs/api/java/security/PublicKey.html``. |
XXXREF. |
|
XXXREF |
|
82 |
While the class is easy to find through the package and class lists |
While the class is easy to find through the package and class lists |
83 |
when looking for a class to represent cryptographical public keys, |
when looking for a class to represent cryptographical public keys, |
84 |
the javadoc is not terribly useful: there is no information |
the javadoc is not terribly useful: there is no information |
85 |
there on how one may create objects that implement this interface. |
there on how one may create objects that implement this interface. |
86 |
The only way to find this out is to click on the ``Use`` link |
The only way to find this out is to click on the ``Use`` link |
87 |
which lists all the occurrences of this class as method |
which lists all the occurrences of this class as method |
88 |
return values or parameters. |
return values or parameters, without much contextual information |
89 |
|
about the importance of the methods. |
90 |
However, what would really help would be a link to the design |
However, what would really help would be a link to the design |
91 |
documentation, even just a UML diagram of what the intended |
documentation, even just a diagram of what the intended |
92 |
uses or lifespans of classes implementing this interface |
uses or lifespans of classes implementing this interface |
93 |
are and how one creates them. |
are and how one creates them. |
94 |
|
These diagrams certainly exist for all properly managed |
95 |
|
medium-to-large scale software projects --- the problem is getting |
96 |
|
them to where it matters. |
97 |
|
|
98 |
In this article, we discuss Navidoc: a system that, given design |
.. at ``http://java.sun.com/j2se/1.4.1/docs/api/java/security/PublicKey.html``. |
99 |
|
|
100 |
|
In this article, we introduce Navidoc: a system that, given design |
101 |
documentation with marked-up UML diagrams, inserts the UML |
documentation with marked-up UML diagrams, inserts the UML |
102 |
diagrams into the classes' javadocs to function as spatial menus. |
diagrams into the classes' javadocs to function as spatial menus. |
103 |
|
|
150 |
[booch-jacobson-rumbaugh98uml-user-guide]_. As a standard it is a |
[booch-jacobson-rumbaugh98uml-user-guide]_. As a standard it is a |
151 |
natural part of software design documentation, because it functions as |
natural part of software design documentation, because it functions as |
152 |
a common language for communication within a software development |
a common language for communication within a software development |
153 |
team. Because UML diagrams should be made anyway, it is good start to |
team. Each UML diagram is meant to expose a particular aspect |
154 |
think about using them also for navigation. |
of the design. |
155 |
|
Therefore |
156 |
The usability of hypertext-based documentation is said to might suffer |
a single program element may appear on several distinct diagrams, |
157 |
from user's disorientation: the tendency to lose one's sense of |
that |
158 |
location and direction in a nonlinear documents |
together create a multicontext view for the element. |
159 |
[conklin87hypertext-onpage-38-40]_. It is also said that the most |
|
160 |
appropriate types of navigation devices should be based on spatiality |
|
161 |
to allow users to develop a cognitive map of the data structure before |
.. Because UML diagrams should be made anyway, it is good start to |
162 |
moving within it [edwards-hardman89lost-in-hyperspace-onpage-123]_. |
think about using them also for navigation. |
163 |
|
(said in intro now) |
164 |
|
|
165 |
|
.. The usability of hypertext-based documentation may suffer |
166 |
|
from user's disorientation: the tendency to lose one's sense of |
167 |
|
location and direction in a nonlinear documents |
168 |
|
[conklin87hypertext-onpage-38-40]_. It is also said that the most |
169 |
|
appropriate types of navigation devices should be based on spatiality |
170 |
|
to allow users to develop a cognitive map of the data structure before |
171 |
|
moving within it [edwards-hardman89lost-in-hyperspace-onpage-123]_. |
172 |
|
|
173 |
Besides UML diagrams are spatial, they are encouraged to be |
Besides UML diagrams are spatial, they are encouraged to be |
174 |
complementary [booch-jacobson-rumbaugh98uml-user-guide-10]_. Therefore |
complementary |
|
a single element may appear in several distinct diagrams, that all |
|
|
together create a multicontext view for the element. ... |
|
175 |
|
|
176 |
.. multicontext views versus traditional hierarchical documentation |
.. multicontext views versus traditional hierarchical documentation |
177 |
|
|
183 |
for documentation navigation, but it's still much better than nothing |
for documentation navigation, but it's still much better than nothing |
184 |
|
|
185 |
- why UML-diagrams would work as menus |
- why UML-diagrams would work as menus |
186 |
|
|
187 |
* UMLs human made abstraction of the system containing |
* UMLs human made abstraction of the system containing |
188 |
all the most relevant parts |
all the most relevant parts |
189 |
|
|
190 |
* don't link to everywhere, but to the most essential places |
* don't link to everywhere, but to the most essential places |
191 |
|
|
192 |
* UMLs are already natural part of the design documentation |
* UMLs are already natural part of the design documentation |
193 |
and thus, familiar to development grew reading documentation |
and thus, familiar to development grew reading documentation |
194 |
|
|