Documentation: Was -- identical() versus sapply()
On 12/04/2016 12:44 PM, David Winsemius wrote:
On Apr 12, 2016, at 8:31 AM, Sarah Goslee <sarah.goslee at gmail.com> wrote: I am very interested in such a distributed documentation editing project, and have some thoughts on how to make it workable for both volunteers and core members who would need to review. I'm willing to lead or colead such a project, if someone stepping up would be a useful first step, and I'm also willing to host a wiki, although I think something like GitHub is probably the best place. I've been contemplating for a while how I can get more involved in the main R efforts, and have contributed to the documentation before, in tiny ways. I think those of us who have participated in R-help for a while have an idea of the main stumbling blocks in the documentation (besides, of course, getting people to read it in the first place). I don't think R-help is the right place to continue discussion; should this be moved to R-devel, or somewhere else entirely?
I'm in. My personal experience with R's documentation has been mostly satisfactory, once I learned to pay careful attention to the words 'list', 'name', and 'expression'. I'm not an experienced C programmer or package author, so the requirement that I submit a "diff" file to an existing document is a hurdle that I cannot not yet clear while running, but I can probably muscle my way over. I remember taking a big step up in learning R when I built a Powerpoint deck to teach basic R, so I would probably learn quite a bit from such a process. My nomination for an improvement 'target' is the `?reshape` page. I've never been able to understand it, despite years of trying, and I've seen many others report a similar experience. Opinion: Its Details section needs to be expanded into two distinct subsections: a 'wide'-direction subsection and a 'long'-direction subsection. Each subsection would outline the minimum number of supplied arguments for an error-free execution. There need to be more worked examples, but those could easily be mined from problems submitted as recorded in the R-help Archives and StackOverFlow.
I'd suggest something different -- that one sounds hard. The revision
history for the last 13 years is shown below. Though my name appears,
it's for trivial changes, and I wouldn't consider myself to be an
author, and I do not offer to participate in the revision.
Duncan
------------------------------------------------------------------------
r68948 | ripley | 2015-08-09 10:51:17 -0400 (Sun, 09 Aug 2015) | 1 line
use https
------------------------------------------------------------------------
r68070 | hornik | 2015-03-24 03:32:16 -0400 (Tue, 24 Mar 2015) | 1 line
Spelling.
------------------------------------------------------------------------
r68059 | ripley | 2015-03-21 18:14:23 -0400 (Sat, 21 Mar 2015) | 1 line
faulty svn merge, one more partial match
------------------------------------------------------------------------
r68055 | ripley | 2015-03-21 16:08:08 -0400 (Sat, 21 Mar 2015) | 1 line
document where use of match.arg allows partial matching
------------------------------------------------------------------------
r61521 | ripley | 2013-01-02 10:09:27 -0500 (Wed, 02 Jan 2013) | 1 line
correction
------------------------------------------------------------------------
r61433 | ripley | 2012-12-25 07:19:50 -0500 (Tue, 25 Dec 2012) | 1 line
remove trailing spaces
------------------------------------------------------------------------
r59039 | ripley | 2012-04-15 06:32:41 -0400 (Sun, 15 Apr 2012) | 1 line
use preferred form of 'R Core Team'
------------------------------------------------------------------------
r57816 | ripley | 2011-12-05 03:08:17 -0500 (Mon, 05 Dec 2011) | 1 line
more tidying up
------------------------------------------------------------------------
r57814 | ripley | 2011-12-05 02:42:30 -0500 (Mon, 05 Dec 2011) | 1 line
add note about duplicate records
------------------------------------------------------------------------
r57094 | maechler | 2011-09-27 11:32:03 -0400 (Tue, 27 Sep 2011) | 1 line
white space only
------------------------------------------------------------------------
r56186 | murdoch | 2011-06-19 21:51:45 -0400 (Sun, 19 Jun 2011) | 1 line
Revert r56184 and r56185
------------------------------------------------------------------------
r56184 | murdoch | 2011-06-19 19:58:46 -0400 (Sun, 19 Jun 2011) | 1 line
Remove redundant \alias entries from man pages
------------------------------------------------------------------------
r53637 | ripley | 2010-11-19 18:13:25 -0500 (Fri, 19 Nov 2010) | 1 line
revise documentation for PR#14435
------------------------------------------------------------------------
r50263 | ripley | 2009-10-30 13:52:33 -0400 (Fri, 30 Oct 2009) | 3 lines
spell 'indices' consistently
add an example of CJK fonts for quartz devices (borrowed from Ei-Ji Nakama)
------------------------------------------------------------------------
r49566 | ripley | 2009-09-04 17:41:50 -0400 (Fri, 04 Sep 2009) | 2 lines
remove unnecessay use of \link[]{} form
------------------------------------------------------------------------
r47616 | ripley | 2009-01-15 17:59:26 -0500 (Thu, 15 Jan 2009) | 2 lines
expand tabs in help files, which were often not rendering as intended
------------------------------------------------------------------------
r47077 | ripley | 2008-12-05 10:59:56 -0500 (Fri, 05 Dec 2008) | 1 line
invalid space
------------------------------------------------------------------------
r42961 | ripley | 2007-09-24 08:43:45 -0400 (Mon, 24 Sep 2007) | 2 lines
try to use \dQuote for actual quotes, and \emph or \sQuote or \code otherwis
------------------------------------------------------------------------
r42667 | pd | 2007-08-27 10:09:08 -0400 (Mon, 27 Aug 2007) | 1 line
reshape revamped, bug in split<-.data.frame
------------------------------------------------------------------------
r42555 | maechler | 2007-08-18 16:11:40 -0400 (Sat, 18 Aug 2007) | 1 line
more \seealso entries (long overdue)
------------------------------------------------------------------------
r42333 | ripley | 2007-07-27 06:16:22 -0400 (Fri, 27 Jul 2007) | 3 lines
add copyright/licence header
remove CVS-style $Id fields
------------------------------------------------------------------------
r41600 | ripley | 2007-05-17 01:08:32 -0400 (Thu, 17 May 2007) | 2 lines
avoid unnecessary/confusing abbrevation of arguments
------------------------------------------------------------------------
r41461 | ripley | 2007-05-07 07:08:51 -0400 (Mon, 07 May 2007) | 1 line
typo
------------------------------------------------------------------------
r41446 | ripley | 2007-05-05 09:17:30 -0400 (Sat, 05 May 2007) | 2 lines
corrections to the handling of \ in Rd files
------------------------------------------------------------------------
r40814 | murdoch | 2007-03-05 12:47:13 -0500 (Mon, 05 Mar 2007) | 1 line
Typos
------------------------------------------------------------------------
r36816 | ripley | 2005-12-20 06:38:29 -0500 (Tue, 20 Dec 2005) | 2 lines
tweaks, usually over-long lines
------------------------------------------------------------------------
r30549 | tlumley | 2004-08-06 16:27:33 -0400 (Fri, 06 Aug 2004) | 2 lines
allow multiple id variables in reshape
------------------------------------------------------------------------
r30449 | ripley | 2004-08-02 10:03:44 -0400 (Mon, 02 Aug 2004) | 2 lines
more removal of unneeded data() statements
------------------------------------------------------------------------
r27501 | ripley | 2003-12-11 03:24:12 -0500 (Thu, 11 Dec 2003) | 2 lines
nls, ts -> stubs
------------------------------------------------------------------------
r27442 | ripley | 2003-12-09 02:24:25 -0500 (Tue, 09 Dec 2003) | 2 lines
split from base