[R] explicit documentation

[Duncan Murdoch]

ronggui wrote:
> It is always unfair to complain about volunteer work, and what you
> should do is to make contributions.
>   

I only half agree with this:  I think that it's fair to complain, as 
long as you make contributions.  With documentation, if you don't think 
it's clear, as part of your complaint you should rewrite it in a way 
that is clear:  then the author can understand what you found unclear 
about it.  (It may well happen that your revision isn't accepted, 
because it may be less clear than the original in the author's opinion, 
or it may be incorrect:  but at least it saves the author the time of 
trying to figure out what you'd prefer.)

Duncan Murdoch
> 2009/4/20 Rolf Turner <r.turner at auckland.ac.nz>:
>   
>> On 19/04/2009, at 8:59 PM, Patrick Burns wrote:
>>
>>     
>>> 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.
>>>       
>>        Why is this unfair?  R-core is supposed to be superhuman! :-)
>>
>>                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.
>>
>>     
>
>
>
>