[R] Help Pages kvetch (was: re Princomp(), prcomp() and loadings() )

[Berton Gunter]

My apologies: This is an R-help kvetch only. 

<kvetch>

I would like to forcefully highlight Brian Ripley's remark:

> The best clue is that the help pages are a very useful 
> resource, but need 
> to be read as carefully as they were written.

This is truly the case (at least for the standard R distribution packages)!!
The help pages are remarkably well written and more often than not include
very informative examples (e.g., plotmath()). Both they and the FAQ's are
valuable resources for "newbies' and longtime R users with porous brains
like me. Hence, I continue to be amazed and disappointed by the number of
questions this list receives that could have been answered by carefully
reading these resources.

So may I make a suggestion: The standard script added to all postings is:
<quote>
PLEASE do read the posting guide!
http://www.R-project.org/posting-guide.html
</quote>

However, this requires the user to take the extra time and effort to
actually peruse the guide, where the admonition to read Help Pages is
contained. Apparently, many fail to do this. So my suggestion is: modify the
above script to:

<quote>
The Help pages provide full,carefully written documentation and numerous
illustrative examples. The FAQ's contain further useful information. PLEASE
consult these resources before posting questions and PLEASE do read the
posting guide, http://www.R-project.org/posting-guide.html, so that the
questions you post can be better answered.
</quote>

I know that this is rather prolix (perhaps others can do better at it), but
maybe it will more directly engage prospective posters and thereby avoid the
need for Brian's and many others frequent reminders. Or do I delude myself
-- again?!

</kvetch>

Cheers,
Bert Gunter