[R] a proposal regarding documentation

[spencerg]

      I agree that the documentation is a primary source, made now more 
accessible with the availability of the RSiteSearch package that allows 
more structures searches of the help pages in contributed packages than 
previously available.  On the other hand, it can sometimes be difficult 
to get the attention and support of someone who can make necessary 
improvements to the help pages. 


      Moreover, the R Wiki should be the primary place for comparing 
similar capabilities in different packages.  For example, a function 
named "gam" appears in two different packages, with similar 
functionality but subtle incompatibilities.  The R Wiki provides a forum 
for an open-ended debate about which is best for which purpose.  The 
Wiki model has proven its worth by allowing anyone to write anything 
they feel moved to write (in the language of their choice).  If 
something is disputed, there are referees to lock particular Wiki pages, 
after which point the dispute can continue but without burdening the 
casual reader with the details.  The success of Wikipedia shows a 
context in which anarchy is almost uniformly superior to prior 
censorship.  The current "task views" provide a very limited overview of 
contributed capabilities but the way those are currently managed make 
them entirely too static and unsuited to this kind of thing.  I plan 
eventually to start contributing to the R Wiki, making comparisons of 
similar capabilities in different packages and inviting the package 
maintainers to correct or expand on anything I write.  However, I have 
other tasks I need to complete before I can start working on that. 


      Best Wishes,
      Spencer Graves


Peter Flom wrote:
> I certainly don't have anything against the WIKI, but I think that the documentation
> is where the action is, especially for newbies.  It's the  natural first step
> when you want to learn about a function or when you  get an error message you 
> don't understand.
>
> Peter
>
> Peter L. Flom, PhD
> Statistical Consultant
> www DOT peterflomconsulting DOT com
>
> ______________________________________________
> R-help at r-project.org mailing list
> 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.
>
>