4 |
|
|
5 |
:Stamp: $Id$ |
:Stamp: $Id$ |
6 |
|
|
7 |
|
2nd round todo: |
8 |
|
=============== |
9 |
|
|
10 |
|
- UML description |
11 |
|
- check metaphor |
12 |
|
- more about stakeholdrer's (antont) |
13 |
|
- javadoc history |
14 |
|
- focus+context menus |
15 |
|
- how our way is placed in |
16 |
|
'Hypermedia and cognition: designing for comprehension' |
17 |
|
- xp |
18 |
|
|
19 |
|
3rd round |
20 |
|
========= |
21 |
|
|
22 |
|
- diagrams |
23 |
|
|
24 |
Introduction |
Introduction |
25 |
============ |
============ |
26 |
|
|
49 |
use UML only for planning and document our software architecture in more |
use UML only for planning and document our software architecture in more |
50 |
general level. We keep UML as a common language for intercommunication |
general level. We keep UML as a common language for intercommunication |
51 |
within our software developer team and within project's all stakeholders. |
within our software developer team and within project's all stakeholders. |
|
(could these stakeholders be identified and described to some extent |
|
|
somewhere? it might be interesting to think also towards users/customers, |
|
|
who in some methods (ways of using XP) control use cases themselves) |
|
52 |
In this purpose we prefer more well abstracted and comprehensible |
In this purpose we prefer more well abstracted and comprehensible |
53 |
human drawn diagrams than exact spesifications matching source code to |
human drawn diagrams than exact spesifications matching source code to |
54 |
every detail: |
every detail: |
58 |
For all but the most trivial systems, a diagram represents an elided |
For all but the most trivial systems, a diagram represents an elided |
59 |
view of the elements that make up a system." [#]_ |
view of the elements that make up a system." [#]_ |
60 |
|
|
61 |
|
: (could these stakeholders be identified and described to some extent |
62 |
|
somewhere? it might be interesting to think also towards users/customers, |
63 |
|
who in some methods (ways of using XP) control use cases themselves) |
64 |
|
|
65 |
.. [#] booch-jacobson-rumbaugh-uml-user-guide, p.24 |
.. [#] booch-jacobson-rumbaugh-uml-user-guide, p.24 |
66 |
|
|
67 |
Altough, even if the architectural documentation won't fully match with |
Altough, even if the architectural documentation won't fully match with |
148 |
|
|
149 |
.. [#] boehm-spiral-model p.64 |
.. [#] boehm-spiral-model p.64 |
150 |
|
|
151 |
|
|
152 |
|
``XXXExtreme Programming`` [#]_ |
153 |
|
|
154 |
|
.. [#] beck99xp |
155 |
|
|
156 |
The nature of our software development process affects also strongly to |
The nature of our software development process affects also strongly to |
157 |
our documentation needs. As we proceed by prototyping and enhancing our |
our documentation needs. As we proceed by prototyping and enhancing our |
158 |
software step by step, also our documentation should be updated in every |
software step by step, also our documentation should be updated in every |
234 |
looked for ways of using hypertext in CASE tools [#]_. Results of its research |
looked for ways of using hypertext in CASE tools [#]_. Results of its research |
235 |
have been used in **MetaEdit+** [#]_ meta CASE tool developed by MetaCase |
have been used in **MetaEdit+** [#]_ meta CASE tool developed by MetaCase |
236 |
Consulting. MetaEdit+ provides bi-directional linking between all its objects |
Consulting. MetaEdit+ provides bi-directional linking between all its objects |
237 |
and interface for reaching linking contexts from diagrams' objects. [ XXX This |
and interface for reaching linking contexts from diagrams' objects. |
238 |
should be checked, but metaphor.it.jyu.fi seems to be down :( ] |
|
239 |
|
: XXX This should be checked, but metaphor.it.jyu.fi seems to be down :( ] |
240 |
|
|
241 |
.. [#] metaphor |
.. [#] metaphor |
242 |
.. [#] lyytinen-kerola-metaphor |
.. [#] lyytinen-kerola-metaphor |
254 |
and fully generated documentation from javadoc comments of each class and method |
and fully generated documentation from javadoc comments of each class and method |
255 |
in the java source code. |
in the java source code. |
256 |
|
|
257 |
The two types of documentation are complementary, as demonstrated in the following table: |
The two types of documentation are complementary, as demonstrated |
258 |
|
in the following table: |
259 |
|
|
260 |
+-----------------------------------+------------------------------------+ |
+-----------------------------------+------------------------------------+ |
261 |
| Design docs | Javadoc | |
| Design docs | Javadoc | |
336 |
|
|
337 |
.. [#] edwards-hardman-lost-in-hyperspace, p.123 |
.. [#] edwards-hardman-lost-in-hyperspace, p.123 |
338 |
|
|
339 |
(See also 'Hypermedia and cognition: designing for comprehension' by Thuring |
: See also 'Hypermedia and cognition: designing for comprehension' by Thuring |
340 |
et al. |
et al. http://portal.acm.org/citation.cfm?id=208348&coll=portal&dl=ACM&CFID=7442809&CFTOKEN=15305251#FullText) |
|
http://portal.acm.org/citation.cfm?id=208348&coll=portal&dl=ACM&CFID=7442809&CFTOKEN=15305251#FullText) |
|
341 |
|
|
342 |
We didn't need to look long for a common navigational metatphor to unify our |
We didn't need to look long for a common navigational metatphor to unify our |
343 |
two distinct documentation. Since the most of our UML-diagrams included objects |
two distinct documentation. Since the most of our UML-diagrams included objects |
482 |
Show instances of arch. docs, javadoc pages &c. Show both diagram and |
Show instances of arch. docs, javadoc pages &c. Show both diagram and |
483 |
then the final hypertext view.`` |
then the final hypertext view.`` |
484 |
|
|
|
In our software development documentation UML diagrams act as multi-ended |
|
|
nexus links, bringing together all documents they relate to. They function |
|
|
like navigation bars or context+focusing menus ``[REFSXXX]`` on the WWW, except |
|
|
that the same page may have several of them. For example a particular class |
|
|
could used in many different contexts and every context could be described |
|
|
by drawing a distinct diagram. Our documentation tool collects all those |
|
|
diagrams into the class documentation page to show all its documented using |
|
|
contexts. |
|
|
|
|
485 |
The pure Javadoc organizes class documentation hierarchically according to |
The pure Javadoc organizes class documentation hierarchically according to |
486 |
their modules packages, but using a single hierarchy is very limited way |
their modules packages, but using a single hierarchy is very limited way |
487 |
of organizing things. An illustrative example of this would be Borge's |
of organizing things. An illustrative example of this would be Borge's |
490 |
.. [#] Borges's "taxonomy" for animals; |
.. [#] Borges's "taxonomy" for animals; |
491 |
http://www.multicians.org/thvv/borges-animals.html |
http://www.multicians.org/thvv/borges-animals.html |
492 |
|
|
493 |
Although, we can |
In our software development documentation UML diagrams act as multi-ended |
494 |
|
nexus links, bringing together all documents they relate to. They function |
495 |
- A Taxonomy of Link Types: |
like navigation bars or context+focusing menus ``[REFSXXX]`` on the WWW, except |
496 |
|
that the same page may have several of them. For example a particular class |
497 |
Thinking about linking... at first we do have UML->reST and |
could be used in many different contexts and every single context could be |
498 |
UML->javadoc links. Because of embedding diagrams implicitly |
described by drawing a distinct diagram. Our documentation tool collects all |
499 |
into target documents we can see linking also as |
those diagrams into the class documentation page to show all its documented |
500 |
bi-directional reST<->javadoc, reST<->reST, and javadoc<->javadoc. |
using contexts. |
501 |
|
|
502 |
Mapping our links to types defined by Trigg |
Because every target document, where a diagram links to, has also a version of |
503 |
|
the diagram, documents are linked bi-directionally. For example, if document A |
504 |
|
has a diagram B, which links to document C, document C has also a version of |
505 |
(Normal links):: |
diagram B, which links back to document A. From our point of view, the links in |
506 |
|
the last version cease to be "links" and the UML diagrams become objects in |
507 |
reST <-> reST Alternate View |
their own right. |
508 |
|
|
509 |
this occurs, when the same diagram is |
When looking only the diagram itself, its links could be divided into two: |
510 |
explicitly referred in two or more architectural |
|
511 |
documents |
1) from the diagram into architecture documentation, and |
512 |
|
2) from the diagram into javadoc source code documentation |
513 |
javadoc -> javadoc Alternate View? |
|
514 |
|
Note, that also links from documentation pages to diagram images exist, |
515 |
We can browse through all classes, which |
but hypertext browser mostly interpret them implicitly by showing the |
516 |
are part of the diagram. Inside the diagram |
embedded diagrams within the documentation pages. |
517 |
only focusing changes. |
|
518 |
|
Still, diagrams are embedded into documentation pages and they should be |
519 |
UML in javadoc -> reST Detail->Summary |
also seen as part of their context. Therefore diagrams links documentation |
520 |
|
also the following ways: |
521 |
UML in reST -> Javadoc General->Spesific or Summary->Detail |
|
522 |
|
3) a javadoc page to an another javadoc page |
523 |
Trigg classifies the following type-pairs for bi-directional |
4) an architectural documentation page to an another architectural documentation |
524 |
links, which can are interpreted oppositionally depending on |
page |
525 |
the direction |
5) a javadoc page to an architectural documentation page, and |
526 |
|
6) an architectural documentation page to a javadoc page |
527 |
- Generalization/Specification |
|
528 |
- Abstraction/Example |
Finally, seeing links as bi-directional will combine links 5) and 6). |
529 |
- Formalization/Application |
The final list of links would be: |
530 |
- Summarization/Detail |
|
531 |
- Simplification/Complication |
1) diagram <-> architecture doc |
532 |
|
2) diagram <-> javadoc |
533 |
:: |
3) architectural doc <-> architectural doc |
534 |
|
4) javadoc <-> javadoc |
535 |
reST <-> javadoc Generalization/Specification |
5) architectural doc <-> javadoc |
536 |
|
|
537 |
|
Trigg Randall (1983) have collected a comprehensive taxonomy of different |
538 |
|
link types [#]_, which also covers link types found in our diagrams. |
539 |
|
Trigg notes that the physical direction of a link defines the manner in |
540 |
|
which readers are expected to follow the link. Though, that wont't rule off |
541 |
|
the possibility that link is typed depenging only on it semantic direction. |
542 |
|
Trigg's taxonomy provides several pairs of such link types. |
543 |
|
|
544 |
|
In our documentation the physical direction of links in a diagram depends by |
545 |
|
the location of explicit include of the diagram. Currently diagrams could be |
546 |
|
included explicitly only in architectural documents and all the links are |
547 |
|
physically directed from the including architectural document to the targets |
548 |
|
defined in the diagram. Most of the links from diagras fall into Trigg's |
549 |
|
pairs of links mentioned above. |
550 |
|
|
551 |
|
An interesting situation comes when a diagram is implicitly embedded into two |
552 |
|
document and provides on and implicit link between them. Even in diagram level |
553 |
|
it includes directed links from from diagram object to its details, in document |
554 |
|
level this is undirected. In our documentation this is the case always when when |
555 |
|
a javadoc page has an implicitly embedded diagram linking to an another javadoc |
556 |
|
page. Within architecture document this is not the case if the other document or |
557 |
|
both of the documents include the diagram explicitly by the author. |
558 |
|
|
559 |
|
|
560 |
|
+----------------------------------------------------------------------------------+ |
561 |
|
| Link in our documentation | Corresponding *normal* link type in | |
562 |
|
| | Trigg's taxonomy | |
563 |
|
+------------------------------------------+---------------------------------------+ |
564 |
|
| | | |
565 |
|
| 1) diagram <-> architecture doc | detail / summary | |
566 |
|
| 2) diagram <-> javadoc | detail / summary | |
567 |
|
| | | |
568 |
|
| 3) architectural doc <-> architectural | explicitly created depends on author | |
569 |
|
| doc | implicitly created is typed as | |
570 |
|
| | alternative view | |
571 |
|
| | | |
572 |
|
| 4) javadoc <-> javadoc | alternative view | |
573 |
|
| 5) architectural doc <-> javadoc | specification / generalization | |
574 |
|
| | | |
575 |
|
+------------------------------------------+---------------------------------------+ |
576 |
|
|
577 |
.. [#] trigg-link-taxonomy |
.. [#] trigg-link-taxonomy |
578 |
|
|
|
From our point of view, the links in the last version cease to be "links" |
|
|
and the UML diagrams become objects in their own right. |
|
579 |
|
|
580 |
Implementation |
Implementation |
581 |
============== |
============== |