[R] a proposal regarding documentation

spencerg spencer.graves at prodsyse.com
Sun Jun 14 19:53:03 CEST 2009


      The documentation for the "nlme" package was improved a few years 
ago by an informal process of this nature.  When I first started 
following r-help, I answered many questions suggesting in part the the 
person read some portion of Pinheiro and Bates (2000).  At that time, 
none of the help pages mentioned Pinheiro and Bates, because they were 
completed before the book and had not been updated.  Eventually, I 
volunteered to add that to some of the help pages.  Doug agreed.  In the 
process, I also expanded some of the examples and modified the text in 
places where I thought I could make it more easily understood. 


      One obvious way to do this would be to provide write access to the 
main R subversion repository.  However, that likely would not be 
acceptable to the R-core team unless it were limited to a very few 
individuals they already knew and trusted, and those individuals could 
process suggestions from others.  As mentioned, there would need to be 
additional ground rules.  For example, an inappropriate example might 
cause "R CMD check" to fail on some platforms but not others.  This 
could expose problems with the core code, which perhaps should be fixed 
but not necessarily in the time frame desired by this new documentation 
improvement team.  For a second example, Brian Ripley once rejected a 
suggested change to a help page because it referred to a package outside 
the core R code. 


      A less threatening alternative might be to direct this energy into 
improving the R Wiki.  I have contributed to other Wiki projects, and 
I've found them to be quite useful and dynamic.  The current R Wiki has 
not so far lived up to its potential.  However, I believe that is just a 
matter of building a critical mass of R Wiki contributors.  Many 
questions on R help could best be answers by first cheking and perhaps 
improving the R Wiki and then directing the questioner to the Wiki.  I 
plan to do that "sometime", but not yet. 


      Hope this helps. 
      Spencer Graves


stephen sefick wrote:
> 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.
>>>       
>
>
>
>




More information about the R-help mailing list