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<pbu...@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<jsor...@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 <peterflomconsult...@mindspring.com> 6/14/2009 7:05 AM >>>
Patrick Burns <pbu...@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@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@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@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.
