137 |
======== |
======== |
138 |
|
|
139 |
We describe automatic linking of design documentation to javadoc |
We describe automatic linking of design documentation to javadoc |
140 |
through UML diagrams embedded in both, acting as nexus links. |
through UML diagrams embedded in both, acting as multi-target nexus links. |
141 |
|
Our simple implementation as a Free Software toolchain is in daily use |
142 |
|
in our project. |
143 |
|
|
144 |
XXX !!! |
XXX !!! |
145 |
|
|
193 |
distinct areas of documentation, and its fairly easy implementation |
distinct areas of documentation, and its fairly easy implementation |
194 |
which supplements the toolchain of other Free Software |
which supplements the toolchain of other Free Software |
195 |
[fsf02categories]_ we use. The other documentation tools can already |
[fsf02categories]_ we use. The other documentation tools can already |
196 |
generate web pages, and the new software injects the added linking to those |
generate web pages, and our new software injects the added linking to those |
197 |
HTML files. The software automatically generates the linking deduced from |
HTML files. The software automatically generates the linking deduced from |
198 |
readily available UML diagram descriptions in our documentation. This |
readily available UML diagram descriptions in our documentation. This |
199 |
means the software was deployable without further authoring. |
means the software was deployable without further authoring. |
213 |
|
|
214 |
The current implementation is a part of and in use at our Free |
The current implementation is a part of and in use at our Free |
215 |
Software project [gzz]_, where it generates the publicly web-browsable |
Software project [gzz]_, where it generates the publicly web-browsable |
216 |
hypertext [gzz_doc_himalia]_ of project's documentation, as a part of |
hypertext [gzz_doc_himalia]_ of the project's documentation, as a part of |
217 |
the toolchain. |
the toolchain. |
218 |
|
|
219 |
.. Javadoc has plenty of unhierarchical links, but they are not meaningful, |
.. Javadoc has plenty of unhierarchical links, but they are not meaningful, |
229 |
software design process contains the following steps |
software design process contains the following steps |
230 |
[parnas-clements86rational-onpage-252-255]_: |
[parnas-clements86rational-onpage-252-255]_: |
231 |
|
|
232 |
- establish and document requirements |
- establish and document requirements |
233 |
- design and document the module structure |
- design and document the module structure |
234 |
- design and document the module interfaces |
- design and document the module interfaces |
235 |
- design and document the uses hierarchy |
- design and document the uses hierarchy |
236 |
- design and document the module internal structures |
- design and document the module internal structures |
237 |
- write programs |
- write programs |
238 |
- maintain (redesign and redevelopment, keeping documentation |
- maintain (redesign and redevelopment, keeping documentation |
239 |
up to date). |
up to date). |
240 |
|
|
241 |
It should be clear that documentation plays major role in the |
It should be clear that documentation plays a major role in the |
242 |
ideal software design process. Steps listed above should produce |
ideal software design process. The steps listed above should produce |
243 |
documentation, which records requirements or design decisions and |
documentation which records requirements or design decisions and |
244 |
could be used as reference manuals throughout the building of the |
could be used as reference manuals throughout the building of the |
245 |
software [brooks75mythical-man-month]_. In theory, in a Free |
software [brooks75mythical-man-month]_. In theory, in a Free |
246 |
Software [fsf02categories]_ project new programmers are always free to |
Software project, new programmers are always free to |
247 |
participate independently. In practice a new programmer could need a |
participate independently. In practice a new programmer may need a |
248 |
lot of mentoring by other group members, before one could be |
lot of mentoring by other group members before being able to contribute |
249 |
productive for the project. Sometimes sufficient mentoring could not |
productively to the project. Sometimes sufficient mentoring isn't |
250 |
even be possible, because members of such a projects could be |
even possible, because members of a project are |
251 |
geographically widely scattered. This results in the Mythical Man |
scattered geographically. This results in the Mythical Man |
252 |
Month effect [brooks75mythical-man-month-onpage-16]_: adding a new member |
Month effect [brooks75mythical-man-month-onpage-16]_: adding a new member |
253 |
into software design process could rather delay than speed up the |
into the software design process delays than speeds up the |
254 |
project. |
project. |
255 |
|
|
256 |
"Men and months are interchangeable commodities only when a task can be |
"Men and months are interchangeable commodities only when a task can be |
263 |
the plan of work.-- --Intercommunication is worse." |
the plan of work.-- --Intercommunication is worse." |
264 |
[brooks75mythical-man-month-onpage-18]_ |
[brooks75mythical-man-month-onpage-18]_ |
265 |
|
|
266 |
Eventually, the greater is the amount of programmers or higher the |
Eventually, the greater the amount of programmers or the higher the |
267 |
turnover within them, the more important it is to have a good |
turnover rate, the more important it is to have good |
268 |
documentation. When new programmers join the project they shouldn't |
documentation. When new programmers join the project they shouldn't |
269 |
have to depend completely on the old staff for their information. An |
have to depend completely on the old staff for finding their way around. An |
270 |
up to date and rational set of documents available for them could |
up to date and rational set of documents available for them could |
271 |
ameliorate the Mythical Man Month effect |
ameliorate the Mythical Man Month effect |
272 |
[parnas-clements86rational-onpage-255]_. |
[parnas-clements86rational-onpage-255]_. |
273 |
|
|
274 |
Because our group is doing experimental research with a rather small |
Because our group is doing experimental research with a rather small |
275 |
group and as an open Free Software project, we need a flexible model |
group and as an open Free Software project, we need a flexible model |
276 |
for software development process. From the classical software |
for software development. From the classical software |
277 |
development process models, ours reminds most of Boehm's Spiral Model |
development process models, ours mostly resembles Boehm's Spiral Model |
278 |
of software development and enhancement [boehm88spiral-model]_. From |
of software development and enhancement [boehm88spiral-model]_. Among |
279 |
the modern models our development process is influenced by Extreme |
the modern models, Extreme Programming [beck99xp]_ is a strong influence |
280 |
Programming [beck99xp]_. The Spiral Model is cyclic and repetitive, |
on our development process. The Spiral Model is cyclic and repetitive, |
281 |
and every cycle has the following phases [boehm88spiral-model-onpage-64]_: |
and every cycle has the following phases [boehm88spiral-model-onpage-64]_: |
282 |
|
|
283 |
* analysis: determining objectives, alternatives, constraints |
* analysis: determining objectives, alternatives, constraints |
284 |
* design: evaluating alternatives, identifying and resolving risks |
* design: evaluating alternatives, identifying and resolving risks |
285 |
* implementation: developing, |
* implementation: developing, |
286 |
* test: verifying |
* test: verifying |
287 |
* planning next phase... |
* planning next phase... |
288 |
|
|
289 |
When comparing the Extreme Programming to the spiral model, the |
When comparing Extreme Programming to the spiral model, |
290 |
Extreme Programming blends all phases of a single Spiral Model's |
Extreme Programming blends all phases of a single Spiral Model's |
291 |
cycle, a little at a time, throughout the entire software development |
cycle, a little at a time, throughout the entire software development |
292 |
process.a single development cycle is even shorter than in the spriral |
process. The development process in Extreme Programming is |
|
model. Though, the development process in Extreme Programming is |
|
293 |
splitted into even smaller cycles and the analysis of the design |
splitted into even smaller cycles and the analysis of the design |
294 |
objects continues throughout the design process. [beck99xp]_ The |
objects continues throughout the design process [beck99xp]_. The |
295 |
Spiral Model emphasizes a lot documenting the changes before |
Spiral Model emphasizes documenting changes before |
296 |
implementing them [boehm88spiral-model]_. The Extreme Programming |
implementing them [boehm88spiral-model]_. Extreme Programming |
297 |
don't speak out much about documentation, but relies on unit tests |
doesn't emphasize documentation very much, relying on unit tests |
298 |
keeping the software coherent and working [beck99xp]_. |
instead for keeping the software coherent and working [beck99xp]_. |
299 |
|
|
300 |
The nature of our software development process affects strongly our |
The nature of our software development process affects strongly our |
301 |
documentation needs. As we proceed by prototyping and enhancing our |
documentation needs. As we proceed by prototyping and enhancing our |