[R] a proposal regarding documentation

[Peter Flom]

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