171 |
generated from the current source for those members, who are working with |
generated from the current source for those members, who are working with |
172 |
particular details. Though, in general documentation rapidly changing details |
particular details. Though, in general documentation rapidly changing details |
173 |
would be irrelevant and confusing. Since currently the main purpose for our |
would be irrelevant and confusing. Since currently the main purpose for our |
174 |
documentation is help intercommunication within our group, we believe manually |
documentation is to help intercommunication within our group, we believe manually |
175 |
made human abstracted documentation serving purposes best. |
made human abstracted documentation serving our purposes best. |
176 |
|
|
177 |
Javadoc |
Javadoc |
178 |
------- |
------- |
179 |
|
|
180 |
Javadoc [#]_ is a hypertext documentation tool developed by Sun |
**Javadoc** [#]_ is a hypertext documentation tool developed by Sun |
181 |
Microsystems and delivered with Sun's Java distribution packages [#]_. |
Microsystems and delivered with Sun's Java distribution packages [#]_. |
182 |
Javadoc generates detailed and well crosslinked documentation analyzing |
Javadoc generates detailed and well crosslinked hypertext documentation |
183 |
classes and including also comments from java source packages. Besides |
analyzing class hierarchies and including documentation comments from |
184 |
crosslinking, Javadoc creates indexes and archical trees as navigational |
java source packages. Besides crosslinking, Javadoc creates indexes and |
185 |
aids for finding individual classes. |
hierarchical trees as navigational aids for locating individual classes. |
186 |
|
|
187 |
.. [#] http://java.sun.com/j2se/javadoc/ |
.. [#] http://java.sun.com/j2se/javadoc/ |
188 |
|
|
189 |
.. [#] Java is a trademark of Sun Microsystems |
.. [#] Java is a trademark of Sun Microsystems |
190 |
|
|
191 |
Sun's distribution of Javadoc tools is proprietary, but there exists |
Sun's distribution of Javadoc tools is proprietary, but there exists |
192 |
also free software (licensed unde GPL) alternatives like doc++ [#]_, |
also free software (licensed unde GPL) alternatives like doc++ [#]_. |
193 |
which can create documentation also from sources of other languages |
Doc++ is designed to create hypertext documentation also from sourcefile |
194 |
(e.g. C++). |
of other languages (e.g. C, C++, perl). |
195 |
|
|
196 |
.. [#] http://docpp.sourceforge.net/ |
.. [#] http://docpp.sourceforge.net/ |
197 |
|
|
198 |
UML |
UML |
199 |
--- |
--- |
200 |
|
|
201 |
- diagrams are from human to human |
**Rational Rose** [#]_ is quite honored UML design tool. It provides a |
202 |
|
direct manipulation interface for drawing different kinds of UML diagrams |
203 |
+ we don't wan to generate diagrams from the code or generate |
into it's data model, which is also supported by other products of Rational |
204 |
code from the diagrams |
Software Corporations Rational product family. In addition of drawing |
205 |
+ generated diagrams are too detailed to be beneficial |
diagrams from scratch, it allows reverse engineering diagrams from |
206 |
+ basic architectural diagrams should be done before code anyway |
code [#]_. |
207 |
(according to software design process models) |
|
208 |
|
Rational Rose could be used with **Rational Soda** [#]_ for creating more |
209 |
Rational Rose |
general architecture documentation. Soda is WYSIWYG (What You See Is What |
210 |
|
You Get) documentation writing tool which allows including diagrams and |
211 |
- part of rational devtool suite |
documentation data from Rational Rose's data model within the written |
212 |
|
documentation. The both, Rational Rose and Rational Soda, are proprietary |
213 |
- quite comprehensive UML design tool for different diagrams (class, |
software and quite expensive for use of small research groups. Problems of |
214 |
sequence, state...) with direct manipulation interface |
direct manipulation and WYSIWYG interfaces are discussed later. |
215 |
- can reverse engingeer diagrams from existing source code |
|
216 |
|
.. [#] http://www.rational.com/products/rose/ |
217 |
- co-operating with Rational Soda, Soda is WYSIWYG |
|
218 |
[pierce-tilley02connecting-documentation-rose] |
.. [#] pierce-tilley02connecting-documentation-rose |
219 |
|
|
220 |
- How should we discuss WYSIWYG, WYSIAYG/WYSIATI for reST &c? Someone will |
.. [#] http://www.rational.com/products/soda/ |
221 |
surely ask about that, |
|
222 |
|
**Dia** [#]_ is a free software (licensed under GPL) alternative for diagram |
223 |
PARTIAL RESOLUTION: |
drawing with direct manipulation user interface. Dia is still more just a |
224 |
|
drawing than design tool, but it can export diagrams in several formats |
225 |
- proprietarity (really?) |
and it has a plugin interface for new drawing object sets. |
|
- 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 |
|
|
|
|
|
- Rational Soda is WYSIWYG, maybe this could be discussed under |
|
|
it |
|
|
|
|
|
- though, because we are coders, we would prefer UML script |
|
|
language over menus and dialogs when creating UML objects |
|
|
|
|
|
+ we need a ref. of criticism of direct manipulation! |
|
|
|
|
|
- not necessarily improve performance, users must learn the meaning |
|
|
of the graphical components, graphic presentation could be |
|
|
misleading, graphical presentation could take excessive screen display |
|
|
space [Shneiderman-direct-manipulation, p. 64] |
|
|
|
|
|
probably only the first argument of performance is relevant |
|
|
anymore... though, creating the graphic presentation for problem |
|
|
could lead to using metaphors and those are often |
|
|
criticized (even by D. Norman :) |
|
|
|
|
|
- "The dark side of a direct manipulation interface is that |
|
|
you have to directly manipulate everything. Instead of an |
|
|
executive who gives high-level instructions, the user is |
|
|
reduced to an assembly line worker who must carry out the |
|
|
same task over and over." |
|
|
[gentner-nielsen-anti-mac, p.74] |
|
|
|
|
|
limits the precision of our actions to the precision |
|
|
achieved with eye-hand-mouse coordination (language and |
|
|
mathematics can be more precise) |
|
|
[gentner-nielsen-anti-mac, p.74] |
|
|
|
|
|
direct manipulation requires the user to be involved in |
|
|
every action, but sometimes the user may not know |
|
|
what to do |
|
|
[gentner-nielsen-anti-mac, p.74] |
|
|
|
|
|
"It's as if we have thrown away a million years of |
|
|
evolution, lost our facility with expressive language, |
|
|
and been reduced to pointing at objects in the immediate |
|
|
environment. -- We have lost all the power of language, and |
|
|
can no longer talk about objects that are not immidiately |
|
|
visible." |
|
|
[gentner-nielsen-anti-mac, p.74] |
|
|
|
|
|
- summaring: direct manipulation could be easy, if there is |
|
|
a natural graphic presentation for the problem. Even then |
|
|
it's not necesesserily the most efficient method. Also the |
|
|
practical point of using the same writing tool foor coding and |
|
|
documenting. |
|
|
|
|
|
+ Rose's problem with direct manipulation: a lot of windows, |
|
|
menus, dialogies etc... to get direct manipulateable graphic |
|
|
representation for everything |
|
|
|
|
|
+ though, directmanipulation is only relevant solution for |
|
|
replacing already created object |
|
|
|
|
|
- proprietary |
|
|
|
|
|
Dia (drawing, generating code templates) |
|
|
|
|
|
- Dia [#]_ is a free software (licensed under GPL) diagram |
|
|
creating program with direct manipulation user interface. |
|
|
- more a drawing than a design tool |
|
226 |
|
|
227 |
.. [#] http://www.lysator.liu.se/~alla/dia/ |
.. [#] http://www.lysator.liu.se/~alla/dia/ |
228 |
|
|
229 |
Doxygen |
**Doxygen** [#]_ is an another Javadoc-like documentation tool, which generates |
230 |
|
hypertext documentation from source code of good variety of different languges. |
231 |
- Doxygen [#]_ is an another Javadoc-like documentation tool, which |
An intresting feature in Doxygen is that it can also generates and embed |
232 |
generates hypertext documentation from source code of good variety |
UML diagrams representing software's class and inheritance hierarchies into |
233 |
of different languges. An intresting feature in Doxygen is that |
class documentation. Also the focused class is higlighted in diagrams on its |
234 |
it generates and embeds UML diagrams representing software's |
documentation pages. Another enhancement for javadoc in Doxygen is that |
235 |
class and inheritance hierarchies into class documentation. Also |
it creates dynamic shrinkable treeview for class hierarchy. |
|
the currently viewed class is higlighted in diagrams. Doxygen |
|
|
also creates shrinkable treeview for class hierarchy. |
|
|
|
|
|
- can generate useless diagrams from the code class hierarchy |
|
|
- should describe somewhere why these are useles... |
|
|
- uses proprietary GraphViz tool to create diagrams |
|
236 |
|
|
237 |
.. [#] http://www.doxygen.org/ |
.. [#] http://www.doxygen.org/ |
238 |
|
|
239 |
MetaPhor, hypertext in soft. devel? [metaphor] |
**MetaPhor** [#]_ Project group in University of Jyväskylä have |
240 |
|
looked for ways of using hypertext in CASE tools[#_]. Results of its research |
241 |
|
have been used in **MetaEdit+**[#]_ meta CASE tool developed by MetaCase |
242 |
|
Consulting. MetaEdit+ provides bi-directional linking between all its objects |
243 |
|
and interface for reaching linking contexts from diagrams' objects. [ XXX This |
244 |
|
should be checked, but metaphor.it.jyu.fi seems to be down :( ] |
245 |
|
|
246 |
|
.. [#] metaphor |
247 |
|
.. [#] lyytinen-kerola-metaphor |
248 |
|
.. [#] http://www.metacase.com/ |
249 |
|
|
|
- bi-directional linking of CASE-tool documents/objects (e.g. double |
|
|
clicking an object opens more detailed diagram, backlink could |
|
|
be found from popup-menu... anyway, a lot of menus to select |
|
|
objects for linking or already linked objects to show) |
|
|
[lyytinen-kerola-metaphor] |
|
|
|
|
|
- MetaEdit+ |
|
|
|
|
|
+ meta CASE tool; could be made to generate code from the diagrams |
|
|
+ could be used to create domain spesific languages, when generating |
|
|
code can really work |
|
|
|
|
|
(We found no open source alternativa to our own development, which |
|
|
combines all the good parts we need from previous tools without |
|
|
reformin dramatically our workin culture.) |
|
250 |
|
|
251 |
Setting of problem |
Setting of problem |
252 |
================== |
================== |
301 |
| | | |
| | | |
302 |
+----------------------------------------+----------------------------------------------+ |
+----------------------------------------+----------------------------------------------+ |
303 |
|
|
304 |
|
|
305 |
|
|
306 |
Problems with the docs: |
Problems with the docs: |
307 |
|
|
308 |
+ Architectural docs easily left in the dark reaches of the filesystem, |
+ Architectural docs easily left in the dark reaches of the filesystem, |
330 |
devices would be those that are spatially based." |
devices would be those that are spatially based." |
331 |
[edward-hardman-lost-in-hyperspace, p.123] |
[edward-hardman-lost-in-hyperspace, p.123] |
332 |
|
|
333 |
|
|
334 |
"Obvious" question: can we increase the overall value by |
"Obvious" question: can we increase the overall value by |
335 |
interconnecting the two? |
interconnecting the two? |
336 |
|
|
534 |
Implementation |
Implementation |
535 |
============== |
============== |
536 |
|
|
537 |
|
(We found no open source alternativa to our own development, which |
538 |
|
combines all the good parts we need from previous tools without |
539 |
|
reformin dramatically our workin culture.) |
540 |
|
|
541 |
+ HTML/WWW browsers don't support bi-directional links |
+ HTML/WWW browsers don't support bi-directional links |
542 |
|
|
543 |
Goals: |
Goals: |
565 |
|
|
566 |
Why UML-language |
Why UML-language |
567 |
|
|
568 |
|
- Doxygen can generate useless diagrams from the code class hierarchy |
569 |
|
should describe somewhere why these are useles... |
570 |
|
uses proprietary GraphViz tool to create diagrams |
571 |
|
|
572 |
|
|
573 |
|
- How should we discuss WYSIWYG, WYSIAYG/WYSIATI for reST &c? Someone will |
574 |
|
surely ask about that, |
575 |
|
|
576 |
|
PARTIAL RESOLUTION: |
577 |
|
|
578 |
|
- proprietarity (really?) |
579 |
|
- versioning much worse |
580 |
|
(changes in rtf could probably be compared?) |
581 |
|
- users = programmers --> used to editing text and compiling, |
582 |
|
it's the most practical to use the same editor as for coding |
583 |
|
- lack of good, **extensible** tools |
584 |
|
|
585 |
|
|
586 |
|
[gentner-nielsen-anti-mac, p.75] collects arguments/argues |
587 |
|
generally against WYSIWYG. |
588 |
|
|
589 |
|
- a document has a rich semantic structure that is poorly |
590 |
|
captured by its appearance on a sceen or printed page |
591 |
|
- other text representations, such as SGML, distinct the semantic |
592 |
|
structure and rules for converting the text and semantics into |
593 |
|
printablepage |
594 |
|
- WYSIWYG assumes there is only one useful representation of the |
595 |
|
information: that of the final reports |
596 |
|
- WYSIWYG assumes people want paper-style reports (and we already |
597 |
|
live within information flood) |
598 |
|
- blind users exists |
599 |
|
|
600 |
|
- Rational Soda is WYSIWYG, maybe this could be discussed under |
601 |
|
it |
602 |
|
|
603 |
|
- though, because we are coders, we would prefer UML script |
604 |
|
language over menus and dialogs when creating UML objects |
605 |
|
|
606 |
|
+ we need a ref. of criticism of direct manipulation! |
607 |
|
|
608 |
|
- not necessarily improve performance, users must learn the meaning |
609 |
|
of the graphical components, graphic presentation could be |
610 |
|
misleading, graphical presentation could take excessive screen display |
611 |
|
space [Shneiderman-direct-manipulation, p. 64] |
612 |
|
|
613 |
|
probably only the first argument of performance is relevant |
614 |
|
anymore... though, creating the graphic presentation for problem |
615 |
|
could lead to using metaphors and those are often |
616 |
|
criticized (even by D. Norman :) |
617 |
|
|
618 |
|
- "The dark side of a direct manipulation interface is that |
619 |
|
you have to directly manipulate everything. Instead of an |
620 |
|
executive who gives high-level instructions, the user is |
621 |
|
reduced to an assembly line worker who must carry out the |
622 |
|
same task over and over." |
623 |
|
[gentner-nielsen-anti-mac, p.74] |
624 |
|
|
625 |
|
limits the precision of our actions to the precision |
626 |
|
achieved with eye-hand-mouse coordination (language and |
627 |
|
mathematics can be more precise) |
628 |
|
[gentner-nielsen-anti-mac, p.74] |
629 |
|
|
630 |
|
direct manipulation requires the user to be involved in |
631 |
|
every action, but sometimes the user may not know |
632 |
|
what to do |
633 |
|
[gentner-nielsen-anti-mac, p.74] |
634 |
|
|
635 |
|
"It's as if we have thrown away a million years of |
636 |
|
evolution, lost our facility with expressive language, |
637 |
|
and been reduced to pointing at objects in the immediate |
638 |
|
environment. -- We have lost all the power of language, and |
639 |
|
can no longer talk about objects that are not immidiately |
640 |
|
visible." |
641 |
|
[gentner-nielsen-anti-mac, p.74] |
642 |
|
|
643 |
|
- summaring: direct manipulation could be easy, if there is |
644 |
|
a natural graphic presentation for the problem. Even then |
645 |
|
it's not necesesserily the most efficient method. Also the |
646 |
|
practical point of using the same writing tool foor coding and |
647 |
|
documenting. |
648 |
|
|
649 |
|
+ Rose's problem with direct manipulation: a lot of windows, |
650 |
|
menus, dialogies etc... to get direct manipulateable graphic |
651 |
|
representation for everything |
652 |
|
|
653 |
|
+ though, directmanipulation is only relevant solution for |
654 |
|
replacing already created object |
655 |
|
|
656 |
|
|
657 |
- not strictly necessary; could have used another editor |
- not strictly necessary; could have used another editor |
658 |
|
|
659 |
- minimum barrier to make a diagram (well, at first have to learn our UML-script) |
- minimum barrier to make a diagram (well, at first have to learn our UML-script) |