1 |
============================================================ |
==================================================================== |
2 |
Bridging Javadoc and design documentation via UML image maps |
Bridging Javadoc and design documentation via UML diagram image maps |
3 |
============================================================ |
==================================================================== |
4 |
|
|
5 |
|
|
6 |
.. "Imagemapped UML diagrams as link nodes" |
.. "Imagemapped UML diagrams as link nodes" |
182 |
its implementation. Finally, we discuss our practical use of the tool |
its implementation. Finally, we discuss our practical use of the tool |
183 |
and conclude. |
and conclude. |
184 |
|
|
185 |
Documentation in Software Engineering |
Background: Documentation in Software Engineering |
186 |
================================================= |
================================================= |
187 |
|
|
188 |
Software engineering process |
Software engineering process |
205 |
up to date). |
up to date). |
206 |
|
|
207 |
It should be clear that documentation plays a major role in the |
It should be clear that documentation plays a major role in the |
208 |
ideal software design process. The steps listed above should produce |
ideal software design process, and that there are several different |
209 |
|
types of documentation at different levels of abstraction. |
210 |
|
The steps listed above should produce |
211 |
documentation which records requirements or design decisions and |
documentation which records requirements or design decisions and |
212 |
could be used as reference manuals throughout the building of the |
could be referenced throughout the building of the |
213 |
software [brooks75mythical-man-month]_. In theory, in a Free |
software [brooks75mythical-man-month]_. |
214 |
Software project, new programmers are always free to |
|
215 |
participate independently. In practice a new programmer may need a |
.. In theory, in a Free |
216 |
|
Software project, new programmers are always free to |
217 |
|
participate independently. |
218 |
|
|
219 |
|
.. Sometimes sufficient mentoring isn't |
220 |
|
even possible, because members of a project are |
221 |
|
scattered geographically. |
222 |
|
|
223 |
|
A programmer joining a project may need a |
224 |
lot of mentoring by other group members before being able to contribute |
lot of mentoring by other group members before being able to contribute |
225 |
productively to the project. Sometimes sufficient mentoring isn't |
productively to the project. |
226 |
even possible, because members of a project are |
This results in the Mythical Man |
|
scattered geographically. This results in the Mythical Man |
|
227 |
Month effect [brooks75mythical-man-month-onpage-16]_: adding a new member |
Month effect [brooks75mythical-man-month-onpage-16]_: adding a new member |
228 |
into the software design process delays rather than speeds up the |
into the software design process delays rather than speeds up the |
229 |
project. |
project. |
245 |
up to date and rational set of documents available for them could |
up to date and rational set of documents available for them could |
246 |
ameliorate the Mythical Man Month effect |
ameliorate the Mythical Man Month effect |
247 |
[parnas-clements86rational-onpage-255]_. |
[parnas-clements86rational-onpage-255]_. |
248 |
|
Improving the learning curve of new programmers may have significant effects. |
249 |
|
|
250 |
Because our group is doing experimental research with a relatively small |
|
251 |
group as an open Free Software project, we need a flexible model |
.. Because our group is doing experimental research with a relatively small |
252 |
for software development. From the classical software |
group as an open Free Software project, we need a flexible model |
253 |
development process models, ours mostly resembles Boehm's Spiral Model |
for software development. From the classical software |
254 |
of software development and enhancement [boehm88spiral-model]_. Among |
development process models, ours mostly resembles Boehm's Spiral Model |
255 |
the modern models, Extreme Programming [beck99xp]_ is a strong influence |
of software development and enhancement [boehm88spiral-model]_. Among |
256 |
on our development process. The Spiral Model is cyclic and repetitive, |
the modern models, Extreme Programming [beck99xp]_ is a strong influence |
257 |
and every cycle has the following phases [boehm88spiral-model-onpage-64]_: |
on our development process. The Spiral Model is cyclic and repetitive, |
258 |
|
and every cycle has the following phases [boehm88spiral-model-onpage-64]_: |
259 |
* analysis: determining objectives, alternatives, constraints |
|
260 |
* design: evaluating alternatives, identifying and resolving risks |
* analysis: determining objectives, alternatives, constraints |
261 |
* implementation: developing, |
* design: evaluating alternatives, identifying and resolving risks |
262 |
* test: verifying |
* implementation: developing, |
263 |
* planning next phase... |
* test: verifying |
264 |
|
* planning next phase... |
265 |
When comparing Extreme Programming to the spiral model, |
|
266 |
Extreme Programming blends all phases of a single Spiral Model's |
When comparing Extreme Programming to the spiral model, |
267 |
cycle, a little at a time, throughout the entire software development |
Extreme Programming blends all phases of a single Spiral Model's |
268 |
process. The development process in Extreme Programming is |
cycle, a little at a time, throughout the entire software development |
269 |
split into smaller cycles and the analysis of the design |
process. The development process in Extreme Programming is |
270 |
objects continues throughout the design process [beck99xp]_. The |
split into smaller cycles and the analysis of the design |
271 |
Spiral Model emphasizes documenting changes before |
objects continues throughout the design process [beck99xp]_. The |
272 |
implementing them [boehm88spiral-model]_. Extreme Programming |
Spiral Model emphasizes documenting changes before |
273 |
doesn't emphasize documentation very much, relying on unit tests |
implementing them [boehm88spiral-model]_. Extreme Programming |
274 |
instead for keeping the software coherent and working [beck99xp]_. |
doesn't emphasize documentation very much, relying on unit tests |
275 |
|
instead for keeping the software coherent and working [beck99xp]_. |
276 |
In our development effort, different parts of the system have |
|
277 |
different needs: the core parts of the system are frozen and |
In our development effort, different parts of the system have |
278 |
require a more formal process for changes, as in the Spiral Model. |
different needs: the core parts of the system are frozen and |
279 |
On the outer edges of the system, new research is taking place and should |
require a more formal process for changes, as in the Spiral Model. |
280 |
not be hampered by process or documentation beyond the immediate |
On the outer edges of the system, new research is taking place and should |
281 |
needs of the group members involved in the development of that particular part. |
not be hampered by process or documentation beyond the immediate |
282 |
|
needs of the group members involved in the development of that particular part. |
283 |
Because of this, it is important for us that the documentation system |
|
284 |
is powerful and flexible: the core parts must have a comprehensive, |
Because of this, it is important for us that the documentation system |
285 |
easily navigable documentation but the documentation for the "edge" |
is powerful and flexible: the core parts must have a comprehensive, |
286 |
must be easy to write and maintain. |
easily navigable documentation but the documentation for the "edge" |
287 |
Thus, our documentation system should support both. |
must be easy to write and maintain. |
288 |
|
Thus, our documentation system should support both. |
289 |
|
|
290 |
|
|
291 |
.. The nature of our software development process affects strongly our |
.. The nature of our software development process affects strongly our |
301 |
intercommunication within our group, we believe manually made human |
intercommunication within our group, we believe manually made human |
302 |
abstracted documentation serves our purposes best. |
abstracted documentation serves our purposes best. |
303 |
|
|
304 |
UML |
UML Diagrams |
305 |
--- |
------------ |
306 |
|
|
307 |
The Unified Modeling Language (UML) is the standard way to visually |
The Unified Modeling Language (UML) is the standard way to visually |
308 |
describe software constructs in diagrams |
describe software constructs in diagrams |
345 |
.. some references to the screenshots here? |
.. some references to the screenshots here? |
346 |
|
|
347 |
|
|
348 |
The problem of two separate pieces of documentation |
The problem of two separate bodies of documentation |
349 |
=================================================== |
=================================================== |
350 |
|
|
351 |
In our project, as probably in most projects that use the Java programming |
In our project, as probably in most projects that use the Java programming |
422 |
documentation and Javadoc, using UML diagrams as multi-ended nexus |
documentation and Javadoc, using UML diagrams as multi-ended nexus |
423 |
links. |
links. |
424 |
|
|
425 |
The design for bi-directional navigation |
|
426 |
======================================== |
A design for multi-directional navigation through UML diagram imagemaps |
427 |
|
======================================================================= |
428 |
|
|
429 |
Usability considerations |
Usability considerations |
430 |
------------------------ |
------------------------ |
526 |
|
|
527 |
.. at least here we should also refer to the screenshots |
.. at least here we should also refer to the screenshots |
528 |
|
|
529 |
Before reaching the current state, our documentation evolved through |
Before reaching its current state, our documentation evolved through |
530 |
several distinct steps, which will be viewed first from the reader's |
several distinct steps, which will be viewed first from the reader's |
531 |
and then from the developer's point of view. |
and then from the developer's point of view. |
532 |
|
|