[Rd] Flat documentation?

[Paul Gilbert]

I am a bit concerned about the direction of some of this discussion. !!Please!!
do not consider gutting the R package Quality Assurance system and start a slide
back to the chaos of Statlib. There has to be a mechanism that weeds out code
that no longer works or is inadequately documented. Do you realize how much time
people have wasted trying to make poorly documented "casual" Statlib code work?
There is nothing that prevents non CRAN distribution of code and casual
documentation. Posting of an r-help message with a web site link does make this
fairly easily accessible to anyone who searches the help archives, and there is
no need for the code or documentation to be in any special format. CRAN also has
a devel area for packages that are not yet in good enough shape for the regular
area.

>In fact, one of my colleagues has chosen to use S-PLUS instead of R
>partly because it's easier to document the stuff he's written. 

I have mostly gone the other way, largely because of the QA tools (which in
large part are possible because of the Rd format). It is worth pointing out to
your colleagues that there is short term pain for long term gain. The fact that
code and documentation arguments are matched, and examples are checked, means
that documentation does not need to be manually checked all the time as your
code evolves. Changes that require changes in the documentation tend to be
pointed out automatically.

Paul Gilbert