barplot manpage (PR#7331)
Hey, Thanks very much for this information.
On Tue, 2 Nov 2004, Patrick Burns wrote:
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.
oops!
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.
I can imagine its tough. I really like the perl model (sorry for brining
this up again) but there is a man page for each function, starting with an
overview (for quick reference) then simple description with some examples,
then a prolonged discussion.
There are several 'overviews' and tutorials in man page style with a
simple organization...
Overview
perl Perl overview (this section)
perlintro Perl introduction for beginners
Tutorials
perlreftut Perl references short introduction
perldsc Perl data structures intro
perlrequick Perl regular expressions quick start
perlboot Perl OO tutorial for beginners
perlbot Perl OO tricks and examples
...
And finally the package ships with the FAQ (which again has a man page
style serchable interface).
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.
Yup, they should be as short as is necessary.
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.
I see what you mean.
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.
Sounds good.
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.
:) I is tough I agree. The user should at least know where to start looking.. Perhaps the R startup text could include a 'where to look' link?
Patrick Burns
Thanks very much for your insight. Should I try to change docs, or should I do something different?
Burns Statistics patrick@burns-stat.com +44 (0)20 8525 0696 http://www.burns-stat.com (home of S Poetry and "A Guide for the Unwilling S User")