[R] a proposal regarding documentation

[Patrick Burns]

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.