141 |
Our simple implementation as a Free Software toolchain is in daily use |
Our simple implementation as a Free Software toolchain is in daily use |
142 |
in our project. |
in our project. |
143 |
|
|
144 |
In this article, we present a navigational aid for software engineering documentation. |
We present a navigational aid for software engineering documentation. |
145 |
Based on using UML diagrams as multi-ended links, the tool connects two |
Based on using UML diagrams as multi-ended links, we hypertexturally |
146 |
|
connect two |
147 |
distinct areas of software engineering documentation: architectural documents and javadoc. |
distinct areas of software engineering documentation: architectural documents and javadoc. |
148 |
|
|
149 |
and its lightweight implementation |
and its lightweight implementation |
167 |
software. |
software. |
168 |
|
|
169 |
In this article, we present a navigational aid for software engineering documentation. |
In this article, we present a navigational aid for software engineering documentation. |
170 |
Based on using UML diagrams as multi-ended links, the tool connects two |
Based on using UML diagrams as multi-ended links, our tool connects two |
171 |
distinct areas of software engineering documentation: architectural documents and javadoc. |
distinct areas of software engineering documentation: architectural documents and javadoc. |
172 |
|
|
173 |
.. XXX This means the software was deployable without further authoring. |
.. XXX This means the software was deployable without further authoring. |
215 |
even possible, because members of a project are |
even possible, because members of a project are |
216 |
scattered geographically. This results in the Mythical Man |
scattered geographically. This results in the Mythical Man |
217 |
Month effect [brooks75mythical-man-month-onpage-16]_: adding a new member |
Month effect [brooks75mythical-man-month-onpage-16]_: adding a new member |
218 |
into the software design process delays than speeds up the |
into the software design process delays rather than speeds up the |
219 |
project. |
project. |
220 |
|
|
221 |
"Men and months are interchangeable commodities only when a task can be |
"Men and months are interchangeable commodities only when a task can be |
228 |
the plan of work.--- ---Intercommunication is worse." |
the plan of work.--- ---Intercommunication is worse." |
229 |
[brooks75mythical-man-month-onpage-18]_ |
[brooks75mythical-man-month-onpage-18]_ |
230 |
|
|
231 |
Eventually, the greater the amount of programmers or the higher the |
Obviously, the greater the amount of programmers or the higher the |
232 |
turnover rate, the more important it is to have good |
turnover rate, the more important it is to have good |
233 |
documentation. When new programmers join the project they shouldn't |
documentation. When new programmers join the project they shouldn't |
234 |
have to depend completely on the old staff for finding their way around. An |
have to depend completely on the old staff for finding their way around. An |
236 |
ameliorate the Mythical Man Month effect |
ameliorate the Mythical Man Month effect |
237 |
[parnas-clements86rational-onpage-255]_. |
[parnas-clements86rational-onpage-255]_. |
238 |
|
|
239 |
Because our group is doing experimental research with a rather small |
Because our group is doing experimental research with a relatively small |
240 |
group and as an open Free Software project, we need a flexible model |
group as an open Free Software project, we need a flexible model |
241 |
for software development. From the classical software |
for software development. From the classical software |
242 |
development process models, ours mostly resembles Boehm's Spiral Model |
development process models, ours mostly resembles Boehm's Spiral Model |
243 |
of software development and enhancement [boehm88spiral-model]_. Among |
of software development and enhancement [boehm88spiral-model]_. Among |
255 |
Extreme Programming blends all phases of a single Spiral Model's |
Extreme Programming blends all phases of a single Spiral Model's |
256 |
cycle, a little at a time, throughout the entire software development |
cycle, a little at a time, throughout the entire software development |
257 |
process. The development process in Extreme Programming is |
process. The development process in Extreme Programming is |
258 |
splitted into even smaller cycles and the analysis of the design |
split into smaller cycles and the analysis of the design |
259 |
objects continues throughout the design process [beck99xp]_. The |
objects continues throughout the design process [beck99xp]_. The |
260 |
Spiral Model emphasizes documenting changes before |
Spiral Model emphasizes documenting changes before |
261 |
implementing them [boehm88spiral-model]_. Extreme Programming |
implementing them [boehm88spiral-model]_. Extreme Programming |
262 |
doesn't emphasize documentation very much, relying on unit tests |
doesn't emphasize documentation very much, relying on unit tests |
263 |
instead for keeping the software coherent and working [beck99xp]_. |
instead for keeping the software coherent and working [beck99xp]_. |
264 |
|
|
265 |
The nature of our software development process affects strongly our |
In our development effort, different parts of the system have |
266 |
documentation needs. As we proceed by prototyping and enhancing our |
different needs: the core parts of the system are frozen and |
267 |
software step by step, also our documentation should be updated in |
require a more formal process for changes, as in the Spiral Model. |
268 |
every cycle. Athough, the detailed implementation is in continual |
On the outer edges of the system, new research is taking place and should |
269 |
change, and we prefer to emphasis the more constant and general design |
not be hampered by process or documentation beyond the immediate |
270 |
documentation. Of course, more detailed up to date documentation could |
needs of the group members. |
271 |
be generated from the current source for those members who are working |
|
272 |
with particular details. Though, in more general design documentation |
Because of this, it is important for us that the documentation system |
273 |
rapidly changing details would be irrelevant and confusing. Since |
is powerful and flexible: the core parts must have a comprehensive, |
274 |
currently the main purpose for our documentation is to help |
easily navigable documentation but the documentation for the "edge" |
275 |
intercommunication within our group, we believe manually made human |
must be easy to write and maintain. |
276 |
abstracted documentation serves our purposes best. |
Thus, our documentation system should support both. |
277 |
|
|
278 |
|
|
279 |
|
.. The nature of our software development process affects strongly our |
280 |
|
documentation needs. As we proceed by prototyping and enhancing our |
281 |
|
software step by step, our documentation should also be updated in |
282 |
|
every cycle. Athough, the detailed implementation is in continual |
283 |
|
change, and we prefer to emphasis the more constant and general design |
284 |
|
documentation. Of course, more detailed up to date documentation could |
285 |
|
be generated from the current source for those members who are working |
286 |
|
with particular details. Though, in more general design documentation |
287 |
|
rapidly changing details would be irrelevant and confusing. Since |
288 |
|
currently the main purpose for our documentation is to help |
289 |
|
intercommunication within our group, we believe manually made human |
290 |
|
abstracted documentation serves our purposes best. |
291 |
|
|
292 |
UML |
UML |
293 |
--- |
--- |