Oh, Lord, give me strength, for I am about to read an R Help file! Give me
insight, for I must parse the words of statisticians forced by R CMD check to
follow the way of the Literate Programmer! And please, Oh Lord, give me the
wisdom to recall these tribulations when I set foot upon that road, that I may
mark the path I blaze clearly for the novitiate to follow yet my words not
become as obscure as those I read!
Commentary:
There is both truth and fiction in Rolf's advice, and for the truth I applaud
the nomination, but for the fiction I fear the picture it paints in the
unsuspecting mind.
On the one hand, it seems odd to ask that the R user believe that meaning is
there because this is software, not the Bible. On the other hand, some people
seem to think they should not have to study to use this tool properly, so
perhaps some faith will help them dig a little harder.
Writing documentation is hard, and R CMD check at least makes package
developers write SOMETHING down. That doesn't mean that it verifies that it is
complete or clearly written. You can drag the horse to water but you cannot
make them drink. Fortunately, the author of the code often does write just what
you need to use it... even if it is a bit terse.
There is also a bit of transformation that happens as one learns how R code
works, that makes the obscure documentation more intuitive. What the beginner
does not seem to realize is that documentation that they would think is perfect
would likely have to be customized to fit their specific set of educational
holes, but would bore others who knew all that stuff. The solution is for
certain conventions and shorthand to be used, and to let the user search as
deep as they need to get their answer. Also, it is common for teenagers to say
they will never be like their parents, yet later find themselves doing just
that.
It is worth reminding new users that the maintainer() function is the key to
helping improve R documentation, since what beginners think of as R is not a
monolithic product but rather is the product of many individuals. Having the
package maintainer be the gateway for such changes is a bit random, since
different maintainers have different time and skills for the job, but
communicating with the right person (rather than expecting them to read every
message on R- help) is in general the best practice for fixing problems in
packages. (Faulty documentation is indeed a problem, but a constructive
suggestion for fixing it is far more likely to bring about change than either
throwing of stones or abasing oneself before the guru.)
---
Jeff NewmillerThe . . Go Live...
DCN:jdnew...@dcn.davis.ca.usBasics: ##.#. ##.#. Live Go...
Live: OO#.. Dead: OO#.. Playing
Research Engineer (Solar/BatteriesO.O#. #.O#. with
/Software/Embedded Controllers) .OO#. .OO#. rocks...1k
---
Sent from my phone. Please excuse my brevity.
Achim Zeileis achim.zeil...@uibk.ac.at wrote:
On Sun, 9 Jun 2013, Duncan Murdoch wrote:
On reading the help pages,
Thanks, online on R-Forge now :-)
Best,
Z
On 13-06-08 9:32 PM, Rolf Turner wrote:
...
You need to get the hang of reading the online help. The
information
required is actually there in ?dotchart --- it's just tersely and
obscurely
expressed. A certain degree of optimism is required. You need to
***believe*** that the information is there; then ask yourself What
could they possibly mean by what they have written that would tell
me what I need to know?.
Duncan Murdoch
__
R-help@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide
http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
__
R-help@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide
http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
__
R-help@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
