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
______________________________________________
R-help@r-project.org mailing list -- To UNSUBSCRIBE and more, see
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.
