33 |
- [humppake] couldn't find yet |
- [humppake] couldn't find yet |
34 |
|
|
35 |
|
|
36 |
Sketching |
Abstract |
37 |
========= |
======== |
38 |
|
|
39 |
- short description about problem: |
We present a navigational aid for documentation used in software |
40 |
* programming language specific tools like javadoc do generate |
development. Based on using readily-authored UML diagrams as multi-ended |
41 |
well navigable documentations from source code |
links, we hypertexturally connect two distinct areas of documentation: design |
42 |
* above them is a human written abstraction to the system |
documents and javadoc program code documentation. |
43 |
as whole - the design documentation |
|
44 |
* how to make these documentation fragments interconnected |
.. Connecting the distinct areas is essential because it could help new |
45 |
with each other with minimum additional work |
developers in getting productive and supports development processes |
46 |
|
where both design and implementation change continuously. |
47 |
Should be searched previous papers, which have research |
|
48 |
quostions alike. Check at first the keywords given by referees |
Introduction |
49 |
of UMLLink article. |
============ |
50 |
|
|
51 |
The usability of xhypertext-based documentation may suffer from user's |
Software projects manage a large base of evolving documentation, which |
52 |
disorientation: the tendency to lose one's sense of location and |
is inter-related on many levels. Design documentation gives |
53 |
direction in a nonlinear document |
architectural views on a more general level, while the program code |
54 |
[conklin87hypertext-onpage-38-40]_. This means that users don't know |
source files contain minute interface specifications and often also |
55 |
where they are in the documentation network or how to get to some |
embedded documentation giving details on how the interfaces should be |
56 |
other place that they know to exist in the network. |
used. |
57 |
|
|
58 |
|
.. Since these parts of documentation are semantically dependent |
59 |
|
they should be interlinked together. |
60 |
|
|
61 |
|
There exist plenty of documentation tools to generate well navigable |
62 |
|
documentations from program code source files. Altough, many of them |
63 |
|
are designed to work with different programming languages, there may |
64 |
|
exist conventions to use specific documentation tool with specific |
65 |
|
programming language (like Javadoc with Java). When a yet another tool |
66 |
|
is used to write the design documentation, linking all documentation |
67 |
|
together by hand would be tedious and error-prone. |
68 |
|
|
69 |
|
.. - short description about problem: |
70 |
|
* programming language specific tools like javadoc do generate |
71 |
|
well navigable documentations from source code |
72 |
|
* above them is a human written abstraction to the system |
73 |
|
as whole - the design documentation |
74 |
|
* how to make these documentation fragments interconnected+ |
75 |
|
with each other with minimum additional work |
76 |
|
|
77 |
|
Should be searched previous papers, which have research |
78 |
|
quostions alike. Check at first the keywords given by referees |
79 |
|
of UMLLink article. |
80 |
|
|
81 |
|
Connecting the distinct areas is essential because it could help new |
82 |
|
developers in getting productive and supports development processes |
83 |
|
where both design and implementation change continuously. |
84 |
|
Our solution to link distinct software development documentations |
85 |
|
together is to base it on UML diagrams which are drawn on design |
86 |
|
documentation to abstract the system under development. We believe |
87 |
|
that advantages of using UML diagrams navigational aids clearly beat |
88 |
|
the minor additional work that is needed. |
89 |
|
|
90 |
|
.. It could be that UML diagrams won't be optimal for navigation of hypertext and |
91 |
|
they won't cover the whole documentation. |
92 |
|
|
93 |
- resolving: |
- resolving: |
94 |
* connecting distinct fragments together using design |
* connecting distinct fragments together using design |
97 |
* several context views (different UML diagrams), multimenu |
* several context views (different UML diagrams), multimenu |
98 |
* spatial navigation (within the diagram) |
* spatial navigation (within the diagram) |
99 |
|
|
100 |
Javadoc [friendly95javadoc]_ is a detailed and fully generated |
Creation of navigational UML diagrams |
101 |
documentation from javadoc comments of each class and method in the |
===================================== |
|
Java source code. |
|
|
|
|
|
Edwards and Hardman [edwards-hardman89lost-in-hyperspace]_ argue that |
|
|
the most appropriate types of navigation devices would be based on |
|
|
spatiality. According to their research, individuals appear to be |
|
|
attempting to create cognitive representations of hypertext structures |
|
|
in the form of a survey-type map. They conlude that users should be |
|
|
allowed 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 [edwards-hardman89lost-in-hyperspace-onpage-123]_. |
|
102 |
|
|
103 |
- why UML |
- why UML |
104 |
* UML is de facto standard for describing software architecture |
* UML is de facto standard for describing software architecture |
107 |
* we do not claim that UML work as the best possible diagrams |
* we do not claim that UML work as the best possible diagrams |
108 |
for documentation navigation, but it's still much better than nothing |
for documentation navigation, but it's still much better than nothing |
109 |
|
|
110 |
In this article we focus on the more conventional use of UML |
.. In this article we focus on the more conventional use of UML to plan |
111 |
to plan and document software |
and document software architecture on a general level. UML can |
112 |
architecture on a general level. |
function as a common language for communication within a software |
113 |
UML can function as a common language for |
development team, and for this purpose we prefer human-drawn |
114 |
communication within a software development team, and for this purpose |
(non-autogenerated) diagrams that show the semantically meaningful |
115 |
we prefer human-drawn (non-autogenerated) diagrams that show the semantically |
features at the right level of abstraction: |
116 |
meaningful features at the right level of abstraction: |
|
117 |
|
.. The usability of xhypertext-based documentation may suffer from user's |
118 |
The distinct pieces (Javadoc and the design documentation) cannot seen as a |
disorientation: the tendency to lose one's sense of location and |
119 |
whole. The obvious question, then, is: can we increase the overall value by |
direction in a nonlinear documents |
120 |
hyperlinking the two distinct pieces of documentation? |
[conklin87hypertext-onpage-38-40]_. This means that users don't know |
121 |
|
where they are in the documentation network or how to get to some |
122 |
When looking at a design document, jumping to the Javadocs to get the |
other place that they know to exist in the network. |
123 |
details would be useful, and when looking at a Javadoc, it would be |
|
124 |
most useful to be able to see if any design documents discuss that class |
.. Edwards and Hardman [edwards-hardman89lost-in-hyperspace]_ argue that |
125 |
or package. |
the most appropriate types of navigation devices would be based on |
126 |
We believe that the design documentation would be read more if |
spatiality. They conlude that users should be allowed to develop a |
127 |
made easily reachable from relevant parts of Javadoc. |
cognitive map of one view of the data structure before being given the |
128 |
|
opinion of navigating through the data some other way |
129 |
|
[edwards-hardman89lost-in-hyperspace-onpage-123]_. |
130 |
|
|
131 |
- why UML-diagrams would work as menus |
- why UML-diagrams would work as menus |
132 |
* UMLs human made abstraction of the system containing |
* UMLs human made abstraction of the system containing |
143 |
* describing is fast |
* describing is fast |
144 |
* setting layout may be more |
* setting layout may be more |
145 |
|
|
146 |
|
Embedding diagrams into HTML |
147 |
|
============================ |
148 |
|
|
149 |
|
Javadoc [friendly95javadoc]_ is a detailed and fully generated |
150 |
|
documentation from javadoc comments of each class and method in the |
151 |
|
Java source code. |
152 |
|
|
153 |
- why html |
- why html |
154 |
* platform and software independent documentation |
* platform and software independent documentation |
155 |
* could be distributed in WWW, intranets etc... as it is |
* could be distributed in WWW, intranets etc... as it is |
168 |
* created under gzz |
* created under gzz |
169 |
* separated as navidoc |
* separated as navidoc |
170 |
|
|
171 |
|
Usage |
172 |
|
===== |
173 |
|
|
174 |
- does it really work |
- does it really work |
175 |
* WWW statistics from himalia, some comparison |
* WWW statistics from himalia, some comparison |
176 |
between pages containing UML and pages that |
between pages containing UML and pages that |
177 |
does not contain |
does not contain |
178 |
* what does the previous prove? |
* what does the previous prove? |
179 |
|
|
180 |
- future |
Conclusion |
181 |
* fenfire |
========== |
182 |
|
|
183 |
|
.. - future |
184 |
|
* fenfire |
185 |
|
|
186 |
|
|
187 |
|
|
188 |
.. bibliography:: gzigzag |
.. bibliography:: gzigzag |