153 |
- can be useful to link even concept with the class that eventually implemented |
- can be useful to link even concept with the class that eventually implemented |
154 |
it. |
it. |
155 |
|
|
156 |
|
- First stage: link only classifiers, and only where the author of the UML |
157 |
|
diagram explicitly specified a link. In interaction diagrams, it's also easy |
158 |
|
to find the relevant method from the javadoc. |
159 |
|
|
160 |
Documentation's reader's point of view |
Documentation's reader's point of view |
161 |
--------------------------------------- |
--------------------------------------- |
162 |
|
|
163 |
Our developing steps: |
When developing |
164 |
|
|
165 |
|
Step 0; distinct architecture documentation with UML diagrams and javadoc generated from the sourcecode. |
166 |
|
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
167 |
|
Advantage over paper: NONE |
168 |
|
|
169 |
- step 0; distinct architecture documentation with UML diagrams |
Step 1; links from architecture documentation's UML-diagrams into relevant javadoc class documentations |
170 |
and javadoc generated from the sourcecode. |
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
|
Advantage over paper: NONE |
|
|
- step 1; links from architecture documentation's UML-diagrams into |
|
|
relevant javadoc class documentations |
|
171 |
+ when only following dummy link into some part of |
+ when only following dummy link into some part of |
172 |
javadoc tree, we would lost the class' context in the architecture |
javadoc tree, we would lost the class' context in the architecture |
173 |
documentation we started |
documentation we started |
174 |
Advantage over paper: MARGINAL: automatize cross-indexing |
Advantage over paper: MARGINAL: automatize cross-indexing |
175 |
- step 2; embedding UML-diagrams into javadoc, linking also them |
|
176 |
|
Step 2; embedding UML-diagrams into javadoc, linking also them |
177 |
|
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" |
178 |
|
|
179 |
+ though, this is not yet enough, because we want to know |
+ though, this is not yet enough, because we want to know |
180 |
where classes are referred in architecture documentation |
where classes are referred in architecture documentation |
181 |
+ "focus+context menu"-metaphor for diagrams needs that we can |
+ "focus+context menu"-metaphor for diagrams needs that we can |
182 |
"step back" from class documentation back to architecture |
"step back" from class documentation back to architecture |
183 |
documentation |
documentation |
184 |
|
|
185 |
|
+ infuriating to the user that the diagram allows navigation |
186 |
|
between *almost* all contexts it is shown in. |
187 |
|
|
188 |
|
+ diagrams a little cluttery |
189 |
|
|
190 |
Advantage over paper: SOME: see the contexts of a class, |
Advantage over paper: SOME: see the contexts of a class, |
191 |
traverse them |
traverse them |
192 |
- step 3; backlinks to the architecture documentation |
|
193 |
+ all this (UML and rerer backlinks) drawn into diagram for consistency |
Step 3; backlinks to the architecture documentation |
194 |
Advantage over paper: MAJOR: multi-end links easily traversable, |
""""""""""""""""""""""""""""""""""""""""""""""""""" |
195 |
structure can be understood |
+ all this (UML and rerer backlinks) drawn into diagram for consistency |
196 |
|
Advantage over paper: MAJOR: multi-end links easily traversable, |
197 |
|
structure can be understood |
198 |
|
|
199 |
|
+ because we can now go to the architectural document from the javadoc, |
200 |
|
we can reduce the size of the diagram in the javadoc by 50%. |
201 |
|
|
202 |
Documentation's developer's point of view |
Documentation's developer's point of view |
203 |
----------------------------------------- |
----------------------------------------- |