[R] explicit documentation

[Wacek Kusnierczyk]

Duncan Murdoch wrote:
> 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:

... and i half agree with this (thus quarter agree with that).  i think
it's pretty fair to complain about unclear documentation *without*
proposing a rewrite.  after all, one may be complaining because one is
unable to understand from the existing docs what the intended and
to-be-documented behaviour is, and this is hardly a position from which
to propose concrete modifications.  but a message that a help page is
unclear can still be useful -- it should, however, clearly explain why
the page is not considered clear. 

vQ


> 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