[R] Documentation General Comments

[Duncan Murdoch]

On 4/22/2008 11:46 AM, Dr. Jeff Miller wrote:
> Bert,
> 
> I don't think the documentation in of itself is the core of the problem
> presented in the original post about this. The problem is one of
> organization. I commented about it possibly being time for an exhaustive R
> Guide (similar to those huge books put out for commercial software) that
> compiles all available documentation. Most importantly, it would have a
> cross-referencing feature. The documentation files have a See Also file but
> they are incomplete and/or obsolete. In my case, I was exacerbated that it
> took over an hour just to find the libraries needed to fully reproduce
> output from SAS PROC FREQ. And, I thought, "Wow, I could have just written a
> function."  But, why do that when the info is out there?  It just needs to
> be more readily and easily accessible.  
> 
> But, now getting to the proposed solution of "then do something about
> it"...are there any legal issues?  It would be time-consuming but not that
> difficult to put help files online that are duplicates of the existing help
> files with the exception that additional See Also terms are included.
> Original text in an author help file would not be edited or deleted without
> author permission. 


R is released under GPL, so if you make changes to the documentation, 
you should also release those under the GPL (or something compatible).

> Another benefit is that other links could be added. For example, the
> existing help files have an Examples section but more could be done with
> this. Links could be provided for annotated examples or to other websites.

If you do this, try to do it in a way that makes it easy to import your 
changes back into the main distribution, and to import changes from the 
main distribution into your docs.  I'm not sure the best way to do that 
if you don't have write permission on the main repository (so you could 
just work on a branch), but surely this is a well-solved problem.

One of the reasons that the core group may seem unresponsive to 
suggestions of changes to the docs is that they usually require quite a 
lot of work to incorporate.  (They are usually incomplete, sometimes 
inconsistent, sometimes inaccurate.)  If you reliably provide patches 
that are complete and accurate and they consistently improve things, 
then you'll find us much more receptive of them.

Duncan Murdoch

> I'm glad to be involved in this.  I'm far from being a guru in R
> programming; this would be a good way to contribute and to continue
> learning.
> 
> 
> Jeff
> 
> 
> 
> 
> 
> -----Original Message-----
> From: r-help-bounces at r-project.org [mailto:r-help-bounces at r-project.org] On
> Behalf Of Bert Gunter
> Sent: Tuesday, April 22, 2008 11:29 AM
> To: r-help at r-project.org
> Subject: Re: [R] Documentation General Comments
> 
> FWIW:
> 
> I consider the documentation of Core R to be one of its great strengths: it
> is terse (read: to the point), detailed, and accurate. I find it eminently
> useful and helpful. Indeed, it was why I made the decision some years ago to
> switch from S-Plus to R (I readily acknowledge that S-Plus may have improved
> its docs since then -- haven't looked at it in years). While I understand
> that it may not suit everyone -- learning styles differ, after all -- may I
> at least say that there is one user out here who is appreciative of the hard
> work and care that has gone into the documentation. Far FAR better than
> anything I could do!
> 
> -- Bert Gunter
> Genentech
> 
> -----Original Message-----
> From: r-help-bounces at r-project.org [mailto:r-help-bounces at r-project.org] On
> Behalf Of Greg Snow
> Sent: Tuesday, April 22, 2008 8:16 AM
> To: Beck, Kenneth (STP); r-help at r-project.org
> Subject: Re: [R] Documentation General Comments
> 
> This is a case of you can't please everyone.  A while back there was
> some complaint that "Introduction to R" spent to much time on talking
> about the different types of variables, just the opposite complaint of
> yours.
> 
> There are several other sources of documentation (look under the books
> link on the R homepage or the contributed documentation link on any CRAN
> site, also browse through the newsletter).  For more in depth
> information on variable types and object oriented programming in R you
> may want to invest in a copy of "S Programming" by Venables and Ripley.
> 
> If you have specific questions (about data types, or other) then tell us
> what you have read and what you still do not understand and you are more
> likely to get a useful answer.  (also read the posting guide that is
> referenced at the bottom of almost all posts to the list).
>