[R] a proposal regarding documentation

[(Ted Harding)]

On 14-Jun-09 22:23:24, Gabor Grothendieck wrote:
> In PHP and also in MySQL the manual has a wiki capability
> so that users can add notes at the end of each page, e.g.
> 
> http://www.php.net/manual/en/functions.variable-functions.php
> 
> http://dev.mysql.com/doc/refman/4.1/en/update.html
> 
> That would combine documentation and wiki into one. Here it would
> involve copying the R help pages into the wiki in a readonly mode
> with the writeable wiki portion at the end of each such page. It
> would also be necessary to be able to update the help pages in the
> wiki when new versions became available.

That is an interesting and potentially very fruitful idea. I'd like
to propose a "quasi-readonly" mode in which wiki users could interpolate
the comments at chosen points within the original text of a help-page
(but without any alteration of the original), with the interpolation
clearly marked by some kind of highlighting (e.g. change of font or
colour).

In that way, a user reading through the original help-page on the
wiki would encounter, in context and in timely fashion, comments
by other users who had themselves met difficulties at that point
and who (hopefully) have provided more detailed guidance and/or
links to other parts of the documentation which illuminate or
fill-in what was not obvious in the first place. With, preferably,
the option to "back up" to where they were before, if they are
led to some other help page.

Ted.

> No explicit email group or coordination would be needed. It would
> also address the organization problem as they could be organized
> as they are now, i.e. into packages: base, stats, utils, ...
> 
> It would require the development of a program to initially copy
> the help pages and to update them while keeping the notes in place
> whenever a new version of R came out.
> 
> On Sun, Jun 14, 2009 at 5:35 PM, Peter
> Flom<peterflomconsulting at mindspring.com> 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.
>>
> 
> ______________________________________________
> 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.

--------------------------------------------------------------------
E-Mail: (Ted Harding) <Ted.Harding at manchester.ac.uk>
Fax-to-email: +44 (0)870 094 0861
Date: 14-Jun-09                                       Time: 23:41:39
------------------------------ XFMail ------------------------------