[R] a proposal regarding documentation

[John Sorkin]

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 th...{{dropped:6}}