R help - Apr 2016 - Documentation: Was -- identical() versus sapply()

On 12/04/16 14:45, Duncan Murdoch wrote:
> On 11/04/2016 10:18 PM, Bert Gunter wrote:
>> "The documentation aims to be accurate, not necessarily
clear."
>>
>> !!!
>>
>> I hope that is not the case! Accurate documentation that is confusing
>> is not very useful.
>
> I don't think it is ever intentionally confusing, but it is often
> concise to the point of obscurity.  Words are chosen carefully, and
> explanations are not repeated.  It takes an effort to read it.  It will
> be clear to careful readers, but not to all readers.
>
> I was thinking of the statement quoted earlier, 'as(x,
"numeric") uses
> the existing as.numeric function'.  That is different than saying
'as(x,
> "numeric") is the same as as.numeric(x)'.

IMHO this is so *obviously* confusing and misleading --- even though it 
is technically correct --- that whoever wrote it was either 
intentionally trying to be confusing or is unbelievably obtuse and/or 
out of touch with reality.

It is not (again IMHO) clear even to *very* careful readers.

To my mind this documentation fails even the fortune(350) test.

cheers,

Rolf

-- 
Technical Editor ANZJS
Department of Statistics
University of Auckland
Phone: +64-9-373-7599 ext. 88276

On 11/04/2016 11:34 PM, Rolf Turner wrote:
> On 12/04/16 14:45, Duncan Murdoch wrote:
>> On 11/04/2016 10:18 PM, Bert Gunter wrote:
>>> "The documentation aims to be accurate, not necessarily
clear."
>>>
>>> !!!
>>>
>>> I hope that is not the case! Accurate documentation that is
confusing
>>> is not very useful.
>>
>> I don't think it is ever intentionally confusing, but it is often
>> concise to the point of obscurity.  Words are chosen carefully, and
>> explanations are not repeated.  It takes an effort to read it.  It will
>> be clear to careful readers, but not to all readers.
>>
>> I was thinking of the statement quoted earlier, 'as(x,
"numeric") uses
>> the existing as.numeric function'.  That is different than saying
'as(x,
>> "numeric") is the same as as.numeric(x)'.
>
>
> IMHO this is so *obviously* confusing and misleading --- even though it
> is technically correct --- that whoever wrote it was either
> intentionally trying to be confusing or is unbelievably obtuse and/or
> out of touch with reality.
>
> It is not (again IMHO) clear even to *very* careful readers.
>
> To my mind this documentation fails even the fortune(350) test.
>
I generally agree that that particular sentence falls pretty far out on 
the obscurity end of the spectrum, but it's much easier to criticize the 
documentation than it is to write it.  I notice that none of the critics 
in this thread have offered improvements on what is there.

I haven't looked up who wrote it (it wasn't me, though I'm sure
I've
written equally obscure sentences), but I do not believe it was 
intentionally confusing, nor is the author obtuse or out of touch with 
reality.  I think that insulting authors is not a way to encourage them 
to change.  That's reality.

Duncan Murdoch

>>>> "The documentation aims to be accurate, not necessarily
clear."
> I notice that none of the critics
> in this thread have offered improvements on what is there.

This issue is as old as documented things. With software it is
particularly nasty, especially when we want the software to function
across many platforms.

Duncan has pointed out that critics need to step up to do something.
I would put documentation failures at the top of my list of
time-wasters, and have been bitten by some particularly weak offerings
(not in R) in the last 2 weeks. So ....

Proposal: That the R community consider establishing a "test and
document" group to parallel R-core to focus on the documentation.
An experiment to test the waters is suggested below.

The needs:
- tools that let the difficulties with documentation be visualized along
with proposed changes and the discussion accessed by the wider
community, while keeping a well-defined process for committing accepted
changes.
- a process for the above. Right now a lot happens by discussion in the
lists and someone in R-core committing the result. If it is
well-organized, it is not well-understood by the wider R user community.
- tools for managing and providing access to tests

At the risk of opening another can of worms, documentation is an area
where such an effort could benefit from paid help. It's an area where
there's low reward for high effort, particularly for volunteers.
Moreover, like many volunteers, I'm happy to do some work, but I need
ways to contribute in small bites (bytes?), and it is difficult to find
suitable tasks to take on.

Is it worth an experiment to customize something like Dokuwiki (which I
believe was the platform for the apparently defunct R wiki) to allow a
segment of R documentation to be reviewed, discussed and changes
proposed? It could show how we might get to a better process for
managing R documentation.

Cheers, JN