Here are a few random thoughts on the documentation issue,
in no particular order.
--Todd
* There is no way to enforce the production of good
documentation. The facilities of S4 being discussed will
certainly help, but good docs will only come from a concerted
effort by the developer. There's much more to good docs than
argument descriptions: examples, theoretical methodology
discussions, pitfall descriptions, literature references,
tutorials, etc. Also, it is frequently (usually?) the case
that a suite of functions needs to be documented at a higher
level than the individual objects.
I suggest that any new "self-documenting" feature of S should
target those parts of documentation that can be reasonably
"forced" during development (say, arg descriptions, return
value descriptions, etc.), but not present itself as the
end-all, be-all documentation system.
* A new documentation system and the resulting texts should be:
- Conducive to easy global text search. Not an index. Not a
keyword search. A global text (regular expression)
search. (Having the index and keywords as well is good,
but not sufficient.)
- Platform independent, but not hostile to platform-dependent
tools. i.e., I want to be able to search the docs with
grep, perl, awk, whatever suits my fancy.
- Not dependent on the use of any particular IDE or editor.
Force me to use <enter your favorite editor> instead of
<enter my favorite editor> and I'll ignore, disable, or
otherwise short-circuit your doc system.
- Conducive to (but not requiring) incorporation into
Makefiles, document control systems (e.g., RCS), etc. (On
the other hand, if make and RCS were required, the world
might be a better place...oops <end opinion>.)
- Not solely reliant on hypertext links. They're handy, but
they're only one view (the rat's-eye view) of the maze.
- Not so high-minded as to discourage the offline production
of "real" documentation (see paragraph above).
- Not so high-minded as to force full docs on simple
one-liners.
- Easily dumped to simple formatted text.
- Easily printed. "Pretty" formats optional.
- Conducive to optional inclusion of sample graphics and such
(emphasis on the optional---the text of the docs should
always be dumpable to plain text).
--
Z. Todd Taylor
Pacific Northwest National Laboratory
Todd.Taylor@pnl.gov
Why is it good to be cool, but bad to be not-so-hot?
-----------------------------------------------------------------------
This message was distributed by s-news@wubios.wustl.edu. To unsubscribe
send e-mail to s-news-request@wubios.wustl.edu with the BODY of the
message: unsubscribe s-news
|