[R] a proposal regarding documentation

[stephen sefick]

That make sense to just do the R-core documentation.  I was suggesting
using my package because I understand it and could have a dialog about
the design choices for the documentation, which would also improve the
package itself.  I am starting my PhD program tomorrow and will
probably not have enough time to be in charge of this, but I wouldn't
mind helping.

Stephen Sefick
On Sun, Jun 14, 2009 at 12:30 PM, Patrick Burns<pburns at pburns.seanet.com> wrote:
> 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.
>



-- 
Stephen Sefick

Let's not spend our time and resources thinking about things that are
so little or so large that all they really do for us is puff us up and
make us feel like gods.  We are mammals, and have not exhausted the
annoying little problems of being mammals.

								-K. Mullis