[R] Fortunes nomination (was: colour coded dotchart)

[Jeff Newmiller]

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 Newmiller                        The     .....       .....  Go Live...
DCN:<jdnewmil at dcn.davis.ca.us>        Basics: ##.#.       ##.#.  Live Go...
                                      Live:   OO#.. Dead: OO#..  Playing
Research Engineer (Solar/Batteries            O.O#.       #.O#.  with
/Software/Embedded Controllers)               .OO#.       .OO#.  rocks...1k
--------------------------------------------------------------------------- 
Sent from my phone. Please excuse my brevity.

Achim Zeileis <Achim.Zeileis at 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 at 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 at 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.