[R] explicit documentation (was: get() versus getAnywhere())

[Patrick Burns]

Rolf Turner wrote:
>
> On 17/04/2009, at 10:21 PM, Duncan Murdoch wrote:
>
>> Benjamin Tyner wrote:
>>> Many thanks Duncan. Perhaps this merits a more explicit note in the
>>> documentation?
>>>
>>
>> The quote I gave is from the documentation.  How could it be more 
>> explicit?
>
> This is unfortunately typical of the attitude of R-core people toward the
> documentation.  ``It's clear.'' they say.  ``It's explicit.''  Clear and
> explicit once you *know* what it's saying.  Not before, but.

I think this unfairly blames R-core for being human.
It takes dedication and a certain skill to be able to
write so that technical issues really are explicit to
those who are not tuned in. 

To demand that talent on top of all of the other talent
present in R-core seems a step too far to me.

I'm of the opinion that help files are among the most
difficult of literary forms.  They need to clearly
state the information, they need to be short enough that
some people might actually read them, they need to
cater to non-native speakers, and they need
to serve their purpose when the reader is frustrated.
(Who reads help files unless they are frustrated?)

It seems to me that help files are a bit like the old
saw about the weather: everyone complains but no one
does anything about it.

"Real" software companies have a documentation
department.  Perhaps there should be a documentation
department for R as well.


Patrick Burns
patrick at burns-stat.com
+44 (0)20 8525 0696
http://www.burns-stat.com
(home of "The R Inferno" and "A Guide for the Unwilling S User")
>
> In this case the documentation is quite opaque to me, and I would suspect
> to a good many like me.  Now that you have made it *genuinely* explicit,
> I can understand what the documentation is saying.  Prior to that I 
> wouldn't
> have had a prayer of guessing that get() would sometimes find things that
> getAnywhere() would not find.
>
> Moreover, if getAnywhere() does not really mean ``get *anywhere*'' 
> then its
> name is misleading.  Surely it wouldn't be too tough to modify 
> getAnywhere()
> so that it really got anywhere.  E.g. get it to call get() when it can't
> find an object with a given name?
>
>     cheers,
>
>         Rolf
>
> ######################################################################
> Attention:\ This e-mail message is privileged and confid...{{dropped:9}}
>
> ______________________________________________
> 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.
>
>