Proposal That a new mailing list be established that pertains exclusively to R documentation. The purpose of the list would be to discuss weak sections of the documentation and establish fixes for those weak spots. Pro If it works, there would be better documentation. It would be an excellent opportunity for newish and/or less technical people to contribute to R. In some respects such people would be much more valuable to the process than very experienced people. It could take some pressure off of R-core. Con It needs at least one person (and probably more) with a strong commitment to make it work. The proposed changes would need to be installed, and activity would need to be encouraged and focused. Background A couple weeks ago I sent a message suggesting that people with issues about the documentation should send a message about it. I left the exact details vague for two reasons: 1) I wasn't sure what the preferred details are. 2) I realized that if people actually followed the suggestion and sent messages about documentation, R-core would be overwhelmed and not especially happy. Patrick Burns patrick at burns-stat.com +44 (0)20 8525 0696 http://www.burns-stat.com (home of "The R Inferno" and "A Guide for the Unwilling S User")
Patrick Burns <pburns at pburns.seanet.com> wrote>Proposal > >That a new mailing list be established >that pertains exclusively to R documentation. >The purpose of the list would be to discuss >weak sections of the documentation and >establish fixes for those weak spots. > > >Pro > >If it works, there would be better documentation. > >It would be an excellent opportunity for newish >and/or less technical people to contribute to R. >In some respects such people would be much more >valuable to the process than very experienced >people. > >It could take some pressure off of R-core. > > >Con > >It needs at least one person (and probably more) >with a strong commitment to make it work. The >proposed changes would need to be installed, and >activity would need to be encouraged and focused. > > >Background > >A couple weeks ago I sent a message suggesting that >people with issues about the documentation should >send a message about it. I left the exact details >vague for two reasons: >1) I wasn't sure what the preferred details are. >2) I realized that if people actually followed >the suggestion and sent messages about documentation, >R-core would be overwhelmed and not especially happy. >I think this is an excellent idea. I would be glad to be one of the "newish or less technical" people. Peter Peter L. Flom, PhD Statistical Consultant www DOT peterflomconsulting DOT com
I neglected to say that I don't have the time to be one of the "drivers" for the proposed list. Pat Patrick Burns wrote:> Proposal > > That a new mailing list be established > that pertains exclusively to R documentation. > The purpose of the list would be to discuss > weak sections of the documentation and > establish fixes for those weak spots. > > > Pro > > If it works, there would be better documentation. > > It would be an excellent opportunity for newish > and/or less technical people to contribute to R. > In some respects such people would be much more > valuable to the process than very experienced > people. > > It could take some pressure off of R-core. > > > Con > > It needs at least one person (and probably more) > with a strong commitment to make it work. The > proposed changes would need to be installed, and > activity would need to be encouraged and focused. > > > Background > > A couple weeks ago I sent a message suggesting that > people with issues about the documentation should > send a message about it. I left the exact details > vague for two reasons: > 1) I wasn't sure what the preferred details are. > 2) I realized that if people actually followed > the suggestion and sent messages about documentation, > R-core would be overwhelmed and not especially happy. > > > > Patrick Burns > patrick at burns-stat.com > +44 (0)20 8525 0696 > http://www.burns-stat.com > (home of "The R Inferno" and "A Guide for the Unwilling S User") > > ______________________________________________ > 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. >
Maybe once the list is going, people who are willing to submit their packages to such scrutiny and critique could join in? Peter -----Original Message----->From: Patrick Burns <pburns at pburns.seanet.com> >Sent: Jun 14, 2009 12:30 PM >To: stephen sefick <ssefick at gmail.com> >Cc: r-help at stat.math.ethz.ch, John Sorkin <jsorkin at grecc.umaryland.edu> >Subject: Re: [R] a proposal regarding documentation > >I had only envisioned the scope of the >list to be the packages that R-core are >responsible for. > >Expanding to contributed packages would >expand both potential usefulness and >certain complexity exponentially. > >Pat > > >stephen sefick wrote: >> I have a package StreamMetabolism. I believe that documentation is >> the toughest part. I find it to be straight foward, but then I wrote >> the package. Lets try one? I don't m >> ind helping. >> >> Stephen Sefick >> >> On Sun, Jun 14, 2009 at 7:23 AM, John Sorkin<jsorkin at grecc.umaryland.edu> wrote: >>> Issues >>> (1) Will people use the new listserver? >>> (2) Will developers respond to postings >>> Question >>> (1) Are there any guidelines for creating documentation? If not should they be developed? It seems to me that every help page should include (a) examples, and when approprate (b) a reference to an article relevant to the help page's content. >>> Thoughts >>> The pages should explain a concept using as little jargon as possible and should try not to be circular, i.e. do not define something using the defined term in its own definition. >>> John >>> >>> >>> >>> John David Sorkin M.D., Ph.D. >>> Chief, Biostatistics and Informatics >>> University of Maryland School of Medicine Division of Gerontology >>> Baltimore VA Medical Center >>> 10 North Greene Street >>> GRECC (BT/18/GR) >>> Baltimore, MD 21201-1524 >>> (Phone) 410-605-7119 >>> (Fax) 410-605-7913 (Please call phone number above prior to faxing) >>> >>>>>> Peter Flom <peterflomconsulting at mindspring.com> 6/14/2009 7:05 AM >>> >>> Patrick Burns <pburns at pburns.seanet.com> wrote >>> >>>> Proposal >>>> >>>> That a new mailing list be established >>>> that pertains exclusively to R documentation. >>>> The purpose of the list would be to discuss >>>> weak sections of the documentation and >>>> establish fixes for those weak spots. >>>> >>>> >>>> Pro >>>> >>>> If it works, there would be better documentation. >>>> >>>> It would be an excellent opportunity for newish >>>> and/or less technical people to contribute to R. >>>> In some respects such people would be much more >>>> valuable to the process than very experienced >>>> people. >>>> >>>> It could take some pressure off of R-core. >>>> >>>> >>>> Con >>>> >>>> It needs at least one person (and probably more) >>>> with a strong commitment to make it work. The >>>> proposed changes would need to be installed, and >>>> activity would need to be encouraged and focused. >>>> >>>> >>>> Background >>>> >>>> A couple weeks ago I sent a message suggesting that >>>> people with issues about the documentation should >>>> send a message about it. I left the exact details >>>> vague for two reasons: >>>> 1) I wasn't sure what the preferred details are. >>>> 2) I realized that if people actually followed >>>> the suggestion and sent messages about documentation, >>>> R-core would be overwhelmed and not especially happy. >>>> >>> >>> I think this is an excellent idea. >>> >>> I would be glad to be one of the "newish or less technical" people. >>> >>> 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. >>> >>> Confidentiality Statement: >>> This email message, including any attachments, is for ...{{dropped:22}} >> >> ______________________________________________ >> 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.Peter L. Flom, PhD Statistical Consultant www DOT peterflomconsulting DOT com
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
Well, suppose I wanted to suggest changes to some documentation, or write an alternate help file for some function. Where would I put it? Let's say I type, in R, ?median. Now suppose I have suggestions. If I look at http://wiki.r-project.org/rwiki/doku.php?id=&idx=rdoc:base I don't see the median listed. Should I add one? OK, I do see mean listed, but the page http://wiki.r-project.org/rwiki/doku.php?id=rdoc:base:mean is blank. Should I edit it? Should it include the original documentation? My proposed changes? Or what? ----- Let's say I figure all that out. Now, someone else disagrees with my documentation and changes it, perhaps making it confusing (in my view). Is this a good way to proceed? Peter Peter L. Flom, PhD Statistical Consultant www DOT peterflomconsulting DOT com
I was studiously ignoring this thread (I have way too much to do already) but Gabor's suggestion reminded me that I have often found the PHP/MySQL online help pages very ... well, helpful. I can't recall the number of times I have scrolled down when I didn't quite get it, and found a comment that got it for me. I find it a really good system. Jim