171 |
that |
that |
172 |
together create a multicontext view for the element. |
together create a multicontext view for the element. |
173 |
|
|
174 |
|
Using UML diagrams as spatial menus to jump around |
175 |
|
the documents for the different program elements |
176 |
|
is attractive exactly because of this: each diagram |
177 |
|
in which an element appears gives some of the necessary |
178 |
|
context for that element. Inserting copies of each UML diagram |
179 |
|
in which a given class appears to its Javadoc as an imagemap |
180 |
|
for jumping to the other related classes |
181 |
|
is a good |
182 |
|
|
183 |
.. Because UML diagrams should be made anyway, it is good start to |
.. Because UML diagrams should be made anyway, it is good start to |
184 |
think about using them also for navigation. |
think about using them also for navigation. |
202 |
* we do not claim that UML work as the best possible diagrams |
* we do not claim that UML work as the best possible diagrams |
203 |
for documentation navigation, but it's still much better than nothing |
for documentation navigation, but it's still much better than nothing |
204 |
|
|
205 |
- why UML-diagrams would work as menus |
.. - why UML-diagrams would work as menus |
206 |
|
|
207 |
* UMLs human made abstraction of the system containing |
* UMLs human made abstraction of the system containing |
208 |
all the most relevant parts |
all the most relevant parts |
209 |
|
|
210 |
* don't link to everywhere, but to the most essential places |
* don't link to everywhere, but to the most essential places |
211 |
|
|
212 |
* UMLs are already natural part of the design documentation |
* UMLs are already natural part of the design documentation |
213 |
and thus, familiar to development grew reading documentation |
and thus, familiar to development grew reading documentation |
214 |
|
|
215 |
Making it easy |
The implementation in Navidoc |
216 |
============== |
============================= |
|
|
|
|
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. |
|
|
|
|
|
- how are UMLs embedded into documentation |
|
217 |
|
|
218 |
* using lexical UML language |
* using lexical UML language |
219 |
|
|
285 |
|
|
286 |
- autogen not comparable to design doc |
- autogen not comparable to design doc |
287 |
|
|
288 |
|
Of course, generated documentation may give well detailed information |
289 |
|
from the current implementation, but the design documentation should |
290 |
|
also cover the future and be rather well abstracted than well |
291 |
|
detailed. Therefore, we want to avoid being bloated by a large amount |
292 |
|
of too detailed diagrams (meanless for us) and prefer fully human |
293 |
|
created diagrams in our design documentation. |
294 |
|
|
295 |
|
- how are UMLs embedded into documentation |
296 |
|
|
297 |
Our approach is different from most tools, |
Our approach is different from most tools, |
298 |
which rely more on automatically generated links [XXX], |
which rely more on automatically generated links [XXX], |
299 |
or inserting connections to the source code [devanbu99chime]_. |
or inserting connections to the source code [devanbu99chime]_. |