Re: [S] RE: Documentation

Z. Todd Taylor (
Thu, 28 May 1998 09:14:30 -0700

Here are a few random thoughts on the documentation issue,
in no particular order.


* 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

- 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
Why is it good to be cool, but bad to be not-so-hot?
This message was distributed by  To unsubscribe
send e-mail to with the BODY of the
message:  unsubscribe s-news