Dan Bolser wrote:
On Tue, 2 Nov 2004, Tony Plate wrote:
Yup, I think you're right. R is a volunteer project, so what needs to happen to improve the documentation is that some capable volunteers (or just one volunteer) step forward. It is the prerogative of the members of R-core to decide whether to spend their time on improving documentation or improving the functionality (or merely having a life).
I thought we had agreed that members of R-core are not allowed lives.
I could try making better pages for the functions I use.
However it is worth noting that R does have really quite good documentation for a piece of software of its kind, compared to both other open source and commercial software.
That is very true. However, I still maintain that the emphasis is on developers and not learners.
[ ...]
As someone who has spent an inordinate amount of time writing and revising help files, I can assure you that writing help files is about as difficult of genre as exists. There are numerous constraints which, taken together, yield no feasible solution.
As you rightly maintain, the help file should be written for people who may not even know what the purpose of the function is, and for people who are not native speakers of the language -- rather than just a mnemonic for the author of the code. On the other hand help files need to be short because no one reads documentation, and no one squared reads long documentation.
Things get even worse for graphics functions -- partly because they are so complex, and partly because we subconsciously think they should be easy because we are well tuned to interpreting the graphics themselves.
At heart it seems to me that you are asking for a new form of help file --
taking them from 2 dimensions to 3. For example, the "axis.lty" item in the
barplot help file would look similar "on the surface" to what it currently is
(though perhaps phrased better). But there would be the ability to drill into
the item to learn about axes, line types and possibly other things.
To implement this vague idea, all that needs to be done is for someone to come up with a workable system, and people to fill in the text.
The big problem that I see with documentation, which you also allude to, is that the (confused and frustrated) user needs to seek out the appropriate documentation when trouble happens. Said confused and frustrated user would rather the documentation came along by itself to say what went wrong. I'm much more at a loss for this.
Patrick Burns
Burns Statistics [EMAIL PROTECTED] +44 (0)20 8525 0696 http://www.burns-stat.com (home of S Poetry and "A Guide for the Unwilling S User")
______________________________________________ [EMAIL PROTECTED] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
