[R] a proposal regarding documentation
John Sorkin
jsorkin at grecc.umaryland.edu
Sun Jun 14 20:48:16 CEST 2009
Perhaps help pages should have links to relevant portions of the WIKI.
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)
>>> spencerg <spencer.graves at prodsyse.com> 6/14/2009 1:53 PM >>>
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.
>>>
>
>
>
>
______________________________________________
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}}
More information about the R-help
mailing list