[R] a proposal regarding documentation

[stephen sefick]

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}}