306 |
cannot seen as whole. Therefore we should make them work as a whole. |
cannot seen as whole. Therefore we should make them work as a whole. |
307 |
|
|
308 |
"Obvious" question: can we increase the overall value by interconnecting the |
"Obvious" question: can we increase the overall value by interconnecting the |
309 |
two distinct documentations? |
two distinct documentations? |
310 |
|
|
311 |
When looking at a design document, jumping to the javadocs to get the details |
When looking at a design document, jumping to the javadocs to get the details |
312 |
would be useful, and when looking at a Javadoc, it would be useful |
would be useful, and when looking at a Javadoc, it would be useful |
313 |
to be able to see if any design documents refer to that class. |
to be able to see if any design documents refer to that class. |
314 |
|
We believe that the architecture document will be read more, after it's |
315 |
|
it's easily reachable from relevant parts of Javadoc. |
316 |
This is the starting point for the toolchain developed in this article. |
This is the starting point for the toolchain developed in this article. |
317 |
|
|
318 |
|
|
319 |
Design |
Design |
320 |
====== |
====== |
321 |
|
|
380 |
Documentation's reader's point of view |
Documentation's reader's point of view |
381 |
--------------------------------------- |
--------------------------------------- |
382 |
|
|
383 |
When developing |
Into current state our documentation evolved through several distinct |
384 |
|
steps, which will be viewed first from the reader's and then from |
385 |
Step 0; distinct architecture documentation with UML diagrams and javadoc generated from the sourcecode. |
the developers point of view. |
386 |
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
|
387 |
- UML diagrams in architecture documentation may link within architectural |
**Step 0; In the beginning we had a distinct architecture documentation with |
388 |
documentation |
UML diagrams and javadoc generated from the sourcecode.** There is probably |
389 |
|
the most common case. The both documentations could comprehensive and well |
390 |
+ objects in UML diagrams which represent parts of the |
navigable by their own, but their information is hard to combine, because there |
391 |
documentation are linked to that parts of documentation |
is no crosslinking between them. |
392 |
|
|
393 |
Advantage over paper: NONE |
Advantage over paper: NONE |
394 |
|
|
395 |
Step 1; links from architecture documentation's UML-diagrams into relevant javadoc class documentations |
**Step 1; Links from architecture documentation's UML diagrams are created |
396 |
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
into relevant javadoc class documentation.** After the first step javadoc was |
397 |
- when we only follow some dummy directed link into some part of |
finally reachable from architecture documentation only by clicking relevant |
398 |
javadoc tree, we would lost the class' context in the architecture |
classes or packages within embedded UML diagrams. Though, after moving to |
399 |
documentation we left (and moved into javadoc) |
the javadoc the context in architectural documentation could be immidiately |
400 |
|
lost. Also there was no links from javadoc to arcitecture documentation. |
|
- objects in UML diagrams which represent java classes |
|
|
are linked to javadoc of those classes |
|
401 |
|
|
402 |
Advantage over paper: MARGINAL: automatize cross-indexing |
Advantage over paper: MARGINAL: automatize cross-indexing |
403 |
|
|
404 |
Step 2; embedding UML-diagrams into javadoc, embedded UML-diagrams' objects also work as links |
**Step 2; UML-diagrams are implicitly embedded into javadoc and embedded |
405 |
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
UML-diagrams' objects also work as links.** After the second step we had |
406 |
- now all objects in UML diagrams could be linked within architecture |
diagrams working as menus between the objects that appeared in diagrams. |
407 |
documentation, from architectural documentation to javadoc, within |
Though, even a single diagram could be used to traverse between all the |
408 |
javadoc or from javadoc to architecture documentation |
documentation pages referred in the diagram, it the original page including |
409 |
|
the diagram was unreachable from the diagram itself. |
|
- though, this is not yet enough, because we want to know |
|
|
where classes are referred in architecture documentation, to be |
|
|
more exact: where those diagrams implicitly embedded into javadoc |
|
|
are explicitly included |
|
|
|
|
|
+ "focus+context menu"-metaphor for diagrams needs that we can |
|
|
"step back" from class documentation back to architecture |
|
|
documentation |
|
410 |
|
|
411 |
Advantage over paper: SOME: see the UML diagram contexts of a class, |
Advantage over paper: SOME: see the UML diagram contexts of a class, |
412 |
traverse them |
traverse them |
413 |
|
|
414 |
Step 3; backlinks to the architecture documentation |
**Step 3; Backlinks to the architecture documentation that include diagrams |
415 |
""""""""""""""""""""""""""""""""""""""""""""""""""" |
is added.** Finally it's possible to "step back" from class documentation |
416 |
- "focus+context menu"-metaphor for diagrams |
back to architecture documentation. After backlinks to the architecture |
417 |
|
documentation is added, a single diagram include an linked object for all |
418 |
+ we highlight the "focused" element of the diagram |
architecture documentation and javadoc pages, where it is explicitly or |
419 |
|
implicitly included. Even the architectural documentation pages were not parts |
420 |
- we can "step back" from class documentation back to architecture |
of the original UML diagrams, they are included in the final image on top of the |
421 |
documentation. |
UML diagram. Putting all these into same graphical images make the all links |
422 |
|
look a consistent whole - like a spatial menu. [XXXREFS??] Also the element in |
423 |
+ all this (UML and refer backlinks) drawn into diagram for consistency |
image representing the current documenta page is focused and target of |
424 |
reasons; this supports "focus+context menu"-metaphor |
focus+contex menu is achieved. |
425 |
|
|
426 |
+ because we can now go to the architectural document from the javadoc, |
Because the original location on the diagrams is easily reachable from its |
427 |
we can reduce the size of the diagram in the javadoc by 50%. |
every implicit occurerrence in javadoc or in architecture documentation, the |
428 |
|
size of the implicitly embedded diagram could be reduced by 50%. The name |
429 |
+ technical note: hovering mouse over diagram will show |
of diagram object is also shown, hovering the pointing device over diagram - also |
430 |
link target class names even on diminished diagrams |
on diminished diagrams. |
431 |
|
|
432 |
Advantage over paper: MAJOR: multi-end links easily traversable, |
Advantage over paper: MAJOR: multi-end links easily traversable, |
433 |
structure can be understood |
structure can be understood |
435 |
Documentation's developer's point of view |
Documentation's developer's point of view |
436 |
----------------------------------------- |
----------------------------------------- |
437 |
|
|
438 |
As little hassle as possible. |
On the developer side, creating diagrams within the arhictecture documentation |
439 |
|
should be as easy and natural as possibel with As little hassle as possible; |
440 |
- minimun barrier to drawing a even small diagram to make |
we want to minimun the barrier of drawing even e small diagram to make |
441 |
document more clear, and to new documents |
documentation more clear. |
442 |
|
|
443 |
After Step 1 from user's perspective, the computer has *all* the information |
For Step 1, we keep it best to demand explicit links in the UML diagrams. User |
444 |
needed for steps 2 and 3, so *no further changes should be required*. |
have to define for each object in UML diagram if it will be linked. For example |
445 |
|
giving a full java class name with package or a relative path to architecture |
446 |
- only explicit link from diagram object to the class it represents is |
documentation page. After Step 1 from user's perspective, the computer has *all* |
447 |
obligatory, all other are implicit |
the information needed for complete also steps 2 and 3, so *no further changes |
448 |
|
should be required*. For example Javadoc comments should not need to be changed |
449 |
For Step 1, it is best to demand explicit links in the UML diagrams. |
at all. |
450 |
|
|
451 |
Steps 2,3: |
During steps 2 and 3 computer only embeds diagrams into previously linked |
452 |
|
documentation pages and creates backlinks to the original documentation |
453 |
- implicitly embed diagrams into relevant code documentation, and |
page. |
|
backlink code documentation to design documentation |
|
|
|
|
|
Javadoc comments should not need to be changed at all. |
|
|
|
|
|
Goals: |
|
|
|
|
|
- "feeling" that the arch. doc will be read because |
|
|
of the backlinks(!) |
|
|
|
|
|
- if diagrams try to link objects, which don't exist (e.g. removed |
|
|
Java class), the linking objects will be specially marked |
|
|
e.g. colored red, or an error when compiling will be given |
|
|
|
|
|
|
|
454 |
|
|
455 |
Analysis from a hypertext theory point of view |
Analysis from a hypertext theory point of view |
456 |
============================================== |
============================================== |