8 |
============ |
============ |
9 |
|
|
10 |
UML (the Unified Modeling Language), founded mainly by Booch, Jacobson and |
UML (the Unified Modeling Language), founded mainly by Booch, Jacobson and |
11 |
Rumbaugh during 1900s to XXX blah blah [#]_, has become the *de facto* |
Rumbaugh during 1900s to ``XXX blah blah`` [#]_, has become the *de facto* |
12 |
industry-standard language for specifying, visualizing, constructing, |
industry-standard language for specifying, visualizing, constructing, |
13 |
and documenting the products in software engineering. Recently, various |
and documenting the products in software engineering. Recently, various |
14 |
approaches have been developed towards unifying software architecture |
approaches have been developed towards unifying software architecture |
18 |
as a visual language, though it's not primarly designed to be a |
as a visual language, though it's not primarly designed to be a |
19 |
programming language [#]_. |
programming language [#]_. |
20 |
|
|
21 |
.. [#] XXX booch-jacobson-rumbaugh-uml-user-guide? |
.. [#] ``XXX`` booch-jacobson-rumbaugh-uml-user-guide? |
22 |
|
|
23 |
.. [#] harrison-barton-raghavachari00uml-to-java |
.. [#] harrison-barton-raghavachari00uml-to-java |
24 |
|
|
149 |
java source packages. Besides crosslinking, Javadoc creates indexes and |
java source packages. Besides crosslinking, Javadoc creates indexes and |
150 |
hierarchical trees as navigational aids for locating individual classes. |
hierarchical trees as navigational aids for locating individual classes. |
151 |
|
|
152 |
XXX Little more about Javadoc's history... |
``XXX Little more about Javadoc's history...`` |
153 |
|
|
154 |
.. [#] friendly95javadoc |
.. [#] friendly95javadoc |
155 |
|
|
290 |
|
|
291 |
The usability of hypertext based documentation may suffer from user's |
The usability of hypertext based documentation may suffer from user's |
292 |
disorientation: the tendency to lose one's sense of location and direction |
disorientation: the tendency to lose one's sense of location and direction |
293 |
in a nonlinear document [#]_. User don't know where she is in the documentation |
in a nonlinear document [#]_. That means, user don't know where she is in |
294 |
network or how to get to some other place that she knows to exist in the network. |
the documentation network or how to get to some other place that she knows |
295 |
|
to exist in the network. In our documentation this gets even more complex, |
296 |
bi-directional crosslinking between those two distinct |
because we have two distinct documentations, which should have somehow |
297 |
documentations and select a common naviational metaphor for them both. |
unified navigation. |
298 |
|
|
299 |
.. [#] conklin-hypertext, pp.38-40 |
.. [#] conklin-hypertext, pp.38-40 |
300 |
|
|
301 |
What can we link? |
Edwards and Hardman [1989] argue that the most appropriate types of |
302 |
|
navigation devices would be spatially based. According to their research |
303 |
"--individuals appear to be attempting to create cognitive |
individuals appear to be attempting to create cognitive representations of |
304 |
representations of hypertext structures in the form of a survey-type |
hypertext structures in the form of a survey-type map. They conlude that |
305 |
map--" |
users should be allobwed to develop a cognitive map of one view of the data |
306 |
[edward-hardman-lost-in-hyperspace, p.123] |
structure before being given the opinion of navigating through the data some |
307 |
|
other way. [#]_ |
|
"Readers should be allobwed to develop a cognitive map of one view |
|
|
of the data structure before being given the opinion of navigating |
|
|
through the data some other way." |
|
|
[edward-hardman-lost-in-hyperspace, p.123] |
|
308 |
|
|
309 |
"The mos appropriate types of navigation |
.. [#] edwards-hardman-lost-in-hyperspace, p.123 |
|
devices would be those that are spatially based." |
|
|
[edward-hardman-lost-in-hyperspace, p.123] |
|
|
|
|
|
|
|
|
- Conceptual |
|
|
|
|
|
+ probably no links for javadoc |
|
|
+ but we can still enhance the linking within |
|
|
the architectural documentation |
|
|
|
|
|
- Specification |
|
|
|
|
|
+ can link Java interfaces |
|
310 |
|
|
311 |
- Implementation |
We didn't need to look long for a common navigational metatphor to unify our |
312 |
|
two distinct documentation. Since the most of our UML-diagrams included objects |
313 |
+ can link all classes |
representing certain Java-classes, it was clear to use those diagrams |
314 |
|
for cross documential navigation. UML-diagrams aren't only shown to |
315 |
- can be useful to link even concept with the class |
readres as map of documentation, but they are also used as spatial |
316 |
that eventually implemented it. |
navigation menu. To be more specifig,we can divide our UML-diagrams |
317 |
|
into three classes: conceptual diagrams, specification diagrams and |
318 |
- Packages to either Java packages, or the package design document |
implementation diagrams. |
319 |
|
|
320 |
|
Different diagram types can be linked within the architectural documentation |
321 |
|
and between the architectural documentation and javadoc as the follow: |
322 |
|
|
323 |
|
|
324 |
|
+-----------------------+------------------------+-----------------------+ |
325 |
|
| Conceptual | Specification | Implementation | |
326 |
|
+-----------------------+------------------------+-----------------------+ |
327 |
|
| | | | |
328 |
|
| + probably no links | + can link Java | + can link all | |
329 |
|
| for javadoc | interface | classes and | |
330 |
|
| | | packages | |
331 |
|
| + the design | + can link also Java | | |
332 |
|
| documentation | packages | | |
333 |
|
| packages could be | | | |
334 |
|
| linked withing the | | | |
335 |
|
| architectural | | | |
336 |
|
| documentation | | | |
337 |
|
| | | | |
338 |
|
| + concepts could be | | | |
339 |
|
| linked with the | | | |
340 |
|
| class that | | | |
341 |
|
| eventially | | | |
342 |
|
| implement it | | | |
343 |
|
| | | | |
344 |
|
+-----------------------+------------------------+-----------------------+ |
345 |
|
|
346 |
Documentation's reader's point of view |
Documentation's reader's point of view |
347 |
--------------------------------------- |
--------------------------------------- |
445 |
Analysis from a hypertext theory point of view |
Analysis from a hypertext theory point of view |
446 |
============================================== |
============================================== |
447 |
|
|
448 |
UML diagram of how architectural documents, UML diagrams and javadoc |
``UML diagram of how architectural documents, UML diagrams and javadoc |
449 |
pages work. Instead of browsing only in one direction, all associations |
pages work. Instead of browsing only in one direction, all associations |
450 |
shown in the diagram should be browsable in either direction! |
shown in the diagram should be browsable in either direction! |
451 |
Show instances of arch. docs, javadoc pages &c. Show both diagram and |
Show instances of arch. docs, javadoc pages &c. Show both diagram and |
452 |
then the final hypertext view. |
then the final hypertext view.`` |
453 |
|
|
454 |
UML diagrams act as multi-ended nexus links, bringing together all |
In our software development documentation UML diagrams act as multi-ended |
455 |
documents they relate to. They function like navigation bars on the |
nexus links, bringing together all documents they relate to. They function |
456 |
WWW, except that the same page may have several of them. |
like navigation bars or context+focusing menus ``[REFSXXX]`` on the WWW, except |
457 |
|
that the same page may have several of them. For example a particular class |
458 |
|
could used in many different contexts and every context could be described |
459 |
|
by drawing a distinct diagram. Our documentation tool collects all those |
460 |
|
diagrams into the class documentation page to show all its documented using |
461 |
|
contexts. |
462 |
|
|
463 |
|
The pure Javadoc organizes class documentation hierarchically according to |
464 |
|
their modules packages, but using a single hierarchy is very limited way |
465 |
|
of organizing things. An illustrative example of this would be Borge's |
466 |
|
"taxonomy" for animals [#]_. |
467 |
|
|
468 |
- make diagrams work as context+focusing menus to the code documentation |
.. [#] Borges's "taxonomy" for animals; |
469 |
|
http://www.multicians.org/thvv/borges-animals.html |
470 |
|
|
471 |
- Borges's "taxonomy" for animals; |
Although, we can |
|
http://www.multicians.org/thvv/borges-animals.html |
|
472 |
|
|
473 |
- A Taxonomy of Link Types: |
- A Taxonomy of Link Types: |
474 |
|
|
477 |
into target documents we can see linking also as |
into target documents we can see linking also as |
478 |
bi-directional reST<->javadoc, reST<->reST, and javadoc<->javadoc. |
bi-directional reST<->javadoc, reST<->reST, and javadoc<->javadoc. |
479 |
|
|
480 |
Mapping our links to types defined by Trigg {trigg-link-taxonomy] |
Mapping our links to types defined by Trigg |
481 |
|
|
482 |
|
|
483 |
(Normal links):: |
(Normal links):: |
484 |
|
|
485 |
reST <-> reST Alternate View |
reST <-> reST Alternate View |
512 |
|
|
513 |
reST <-> javadoc Generalization/Specification |
reST <-> javadoc Generalization/Specification |
514 |
|
|
515 |
|
|
516 |
|
.. [#] trigg-link-taxonomy |
517 |
|
|
518 |
From our point of view, the links in the last version cease to be "links" |
From our point of view, the links in the last version cease to be "links" |
519 |
and the UML diagrams become objects in their own right. |
and the UML diagrams become objects in their own right. |
520 |
|
|