214 |
|
|
215 |
- provide a plugin interface for different documentation tools |
- provide a plugin interface for different documentation tools |
216 |
|
|
217 |
|
Up to this article, all steps except the last one are implemented. The |
|
Up to this article all steps except the last one are implemented. The |
|
218 |
existing tools we selected as the basis for our documentation tool |
existing tools we selected as the basis for our documentation tool |
219 |
are: Javadoc [friendly95javadoc]_, Docutils [goodger02docutils]_, and |
are: Javadoc [friendly95javadoc]_, Docutils [goodger02docutils]_, and |
220 |
our own UML diagram description tool. Further, the UML tool uses |
our own UML diagram description tool. Further, the UML tool uses |
228 |
alternative or using them as parallel should be possible with only |
alternative or using them as parallel should be possible with only |
229 |
minor plugin programming. |
minor plugin programming. |
230 |
|
|
231 |
it is also |
The javadoc format is the standard way to include documentation in |
232 |
|
Java source code [friendly95javadoc]_. Generating the WWW pages is not |
233 |
The javadoc format is the standard way to include documentation in Java |
a complicated process, and at the moment GNU Classpath Tools |
234 |
source code. Generating the WWW pages is not a complicated process, and at the |
[fsf02classpath]_ is developing a Free Software implementation called |
235 |
moment GNU Classpath Tools is developing a Free Software implementation called |
gjdoc. Also many other Javadoc like Free Software tools for exists - |
236 |
gjdoc. As Javadoc has provided good enough fully generated and up-to-date |
many of them supporting multiple programming languages including Java. |
237 |
detailed documentation for our use, we have had no reason to abandon it yet. |
|
238 |
|
.. As Javadoc has |
239 |
On the |
provided good enough fully generated and up-to-date detailed |
240 |
|
documentation for our use, we have had no reason to abandon it yet. |
241 |
Although our UML language was already implemented before the linking |
|
242 |
tool, which finally created the bi-directional linking between |
UML tool |
243 |
documentations, we discuss shortly how we arrived at creating a |
-------- |
244 |
language instead of using a diagram drawing tool with direct |
|
245 |
manipulation GUI. |
Our UML description tool was already implemented before the |
246 |
|
documentation linking tool, which finally enabled the bi-directional |
247 |
|
linking between distinctdocumentations. In the following we discuss |
248 |
- flow diagram of the implementation |
shortly, how we ended up to use this our own lexical UML language |
249 |
|
instead of using already existing free diagram drawing tool like Dia |
250 |
reST's filosophy |
[larsson03dia]_, or CASE-tool like AgroUML [tigris03argouml]_. |
251 |
|
|
252 |
- indentation for blocks |
.. There exist also such Javadoc like tools, which generate some embedded |
253 |
- robust for erros |
diagrams into documentation. Doxygen [heesch03doxygen]_ ,for example, |
254 |
- "natural" to write |
generates diagrams of class inheritance tree. Also proprietary |
255 |
- "ASCII layout" (our language for UML is an exception, which is discussed |
Rational Rose has could be |
|
later) |
|
|
|
|
|
Why UML description language |
|
|
|
|
|
- Doxygen can generate useless diagrams from the code class hierarchy |
|
|
* should describe somewhere why these are useles... |
|
|
* uses proprietary GraphViz tool to create diagrams |
|
|
|
|
|
|
|
|
- How should we discuss WYSIWYG, WYSIAYG/WYSIATI for reST &c? Someone will |
|
|
surely ask about that, |
|
|
|
|
|
PARTIAL RESOLUTION: |
|
|
|
|
|
- proprietarity (really?) |
|
|
- versioning much worse |
|
|
(changes in rtf could probably be compared?) |
|
|
- users = programmers --> used to editing text and compiling, |
|
|
it's the most practical to use the same editor as for coding |
|
|
- lack of good, **extensible** tools |
|
|
|
|
|
|
|
|
[gentner-nielsen-anti-mac, p.75] collects arguments/argues |
|
|
generally against WYSIWYG. |
|
|
|
|
|
- a document has a rich semantic structure that is poorly |
|
|
captured by its appearance on a sceen or printed page |
|
|
- other text representations, such as SGML, distinct the semantic |
|
|
structure and rules for converting the text and semantics into |
|
|
printablepage |
|
|
- WYSIWYG assumes there is only one useful representation of the |
|
|
information: that of the final reports |
|
|
- WYSIWYG assumes people want paper-style reports (and we already |
|
|
live within information flood) |
|
|
- blind users exists |
|
256 |
|
|
257 |
- Rational Soda is WYSIWYG, maybe this could be discussed under |
Though,as discussed earlier, we wanted to use human created diagrams |
258 |
it |
in our design documentation. |
259 |
|
|
260 |
- though, because we are coders, we would prefer UML description |
- though, because we are coders, we would prefer UML description |
261 |
language over menus and dialogs when creating UML diagrams |
language over menus and dialogs when creating UML diagrams |
311 |
replacing already created object |
replacing already created object |
312 |
|
|
313 |
|
|
314 |
|
- How should we discuss WYSIWYG, WYSIAYG/WYSIATI for reST &c? Someone will |
315 |
|
surely ask about that, |
316 |
|
|
317 |
|
PARTIAL RESOLUTION: |
318 |
|
|
319 |
|
- proprietarity (really?) |
320 |
|
- versioning much worse |
321 |
|
(changes in rtf could probably be compared?) |
322 |
|
- users = programmers --> used to editing text and compiling, |
323 |
|
it's the most practical to use the same editor as for coding |
324 |
|
- lack of good, **extensible** tools |
325 |
|
|
326 |
|
|
327 |
|
Docutils |
328 |
|
-------- |
329 |
|
|
330 |
|
reST's filosophy |
331 |
|
|
332 |
|
- indentation for blocks |
333 |
|
- robust for erros |
334 |
|
- "natural" to write |
335 |
|
- "ASCII layout" (our language for UML is an exception, which is discussed |
336 |
|
later) |
337 |
|
|
338 |
|
|
339 |
|
[gentner-nielsen96anti-mac, p.75] collects arguments/argues |
340 |
|
generally against WYSIWYG. |
341 |
|
|
342 |
|
- a document has a rich semantic structure that is poorly |
343 |
|
captured by its appearance on a sceen or printed page |
344 |
|
- other text representations, such as SGML, distinct the semantic |
345 |
|
structure and rules for converting the text and semantics into |
346 |
|
printablepage |
347 |
|
- WYSIWYG assumes there is only one useful representation of the |
348 |
|
information: that of the final reports |
349 |
|
- WYSIWYG assumes people want paper-style reports (and we already |
350 |
|
live within information flood) |
351 |
|
- blind users exists |
352 |
|
|
353 |
|
- Rational Soda is WYSIWYG, maybe this could be discussed under |
354 |
|
it |
355 |
|
|
356 |
|
|
357 |
- not strictly necessary; could have used another editor |
- not strictly necessary; could have used another editor |
358 |
|
|
359 |
- minimum barrier to make a diagram (well, at first have to learn our |
- minimum barrier to make a diagram (well, at first have to learn our |
367 |
|
|
368 |
+ graphical placing would need an GUI |
+ graphical placing would need an GUI |
369 |
|
|
370 |
|
|
371 |
|
- flow diagram of the implementation |
372 |
|
|
373 |
|
reST's filosophy |
374 |
|
|
375 |
|
- indentation for blocks |
376 |
|
- robust for erros |
377 |
|
- "natural" to write |
378 |
|
- "ASCII layout" (our language for UML is an exception, which is discussed |
379 |
|
later) |
380 |
|
|
381 |
|
|
382 |
- diagrams in the same reST source as the architecture document |
- diagrams in the same reST source as the architecture document |
383 |
|
|
384 |
- separate UML structure from presentation, show structure in easily |
- separate UML structure from presentation, show structure in easily |