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? Sarah On Tue, Apr 12, 2016 at 11:06 AM, Bert Gunter <bgunter.4567 at gmail.com> wrote:> FWIW: > > 1. I agree that this is an idea worth considering. Especially now that > R has become so widely used among practitioners who are neither > especially software literate nor interested in poring over R manuals > (as I did when I first learned R). They have explicit tasks to do and > just want to get to them as directly as possible. > > 2. A partial reply to the (fair) criticism of those who criticize docs > without offering improvements is that one may not know what > improvement to offer precisely because the docs do not make it clear. > This proposal or something similar addresses this issue. The experts > could adjudicate. > > 3. I agree: writing good docs is hard. Having a mechanism like this > would also help non-native English writers of software (or challenged > native writers like me!) . > > 4. I also think John is right, that if the right mechanism were found > so that small efforts could be accumulated, a lot of us would > participate. A wiki sounds about right, but I bow to those with > greater wisdom and experience here. > > 5. The danger here is that this would suck a lot of time from R core. > That's unacceptable. Presumably a wiki (self-correcting?) would help > avoid this. > > Cheers, > Bert > Bert Gunter > > "The trouble with having an open mind is that people keep coming along > and sticking things into it." > -- Opus (aka Berkeley Breathed in his "Bloom County" comic strip ) > > > On Tue, Apr 12, 2016 at 6:21 AM, ProfJCNash <profjcnash at gmail.com> wrote: >> >>>>>> "The documentation aims to be accurate, not necessarily clear." >>> I notice that none of the critics >>> in this thread have offered improvements on what is there. >> >> >> This issue is as old as documented things. With software it is >> particularly nasty, especially when we want the software to function >> across many platforms. >> >> Duncan has pointed out that critics need to step up to do something. >> I would put documentation failures at the top of my list of >> time-wasters, and have been bitten by some particularly weak offerings >> (not in R) in the last 2 weeks. So .... >> >> Proposal: That the R community consider establishing a "test and >> document" group to parallel R-core to focus on the documentation. >> An experiment to test the waters is suggested below. >> >> The needs: >> - tools that let the difficulties with documentation be visualized along >> with proposed changes and the discussion accessed by the wider >> community, while keeping a well-defined process for committing accepted >> changes. >> - a process for the above. Right now a lot happens by discussion in the >> lists and someone in R-core committing the result. If it is >> well-organized, it is not well-understood by the wider R user community. >> - tools for managing and providing access to tests >> >> At the risk of opening another can of worms, documentation is an area >> where such an effort could benefit from paid help. It's an area where >> there's low reward for high effort, particularly for volunteers. >> Moreover, like many volunteers, I'm happy to do some work, but I need >> ways to contribute in small bites (bytes?), and it is difficult to find >> suitable tasks to take on. >> >> Is it worth an experiment to customize something like Dokuwiki (which I >> believe was the platform for the apparently defunct R wiki) to allow a >> segment of R documentation to be reviewed, discussed and changes >> proposed? It could show how we might get to a better process for >> managing R documentation. >> >> Cheers, JN >>-- Sarah Goslee http://www.functionaldiversity.org
David Winsemius
2016-Apr-12 16:44 UTC
[R] Documentation: Was -- identical() versus sapply()
> 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. -- David.> > Sarah > > On Tue, Apr 12, 2016 at 11:06 AM, Bert Gunter <bgunter.4567 at gmail.com> wrote: >> FWIW: >> >> 1. I agree that this is an idea worth considering. Especially now that >> R has become so widely used among practitioners who are neither >> especially software literate nor interested in poring over R manuals >> (as I did when I first learned R). They have explicit tasks to do and >> just want to get to them as directly as possible. >> >> 2. A partial reply to the (fair) criticism of those who criticize docs >> without offering improvements is that one may not know what >> improvement to offer precisely because the docs do not make it clear. >> This proposal or something similar addresses this issue. The experts >> could adjudicate. >> >> 3. I agree: writing good docs is hard. Having a mechanism like this >> would also help non-native English writers of software (or challenged >> native writers like me!) . >> >> 4. I also think John is right, that if the right mechanism were found >> so that small efforts could be accumulated, a lot of us would >> participate. A wiki sounds about right, but I bow to those with >> greater wisdom and experience here. >> >> 5. The danger here is that this would suck a lot of time from R core. >> That's unacceptable. Presumably a wiki (self-correcting?) would help >> avoid this. >> >> Cheers, >> Bert >> Bert Gunter >> >> "The trouble with having an open mind is that people keep coming along >> and sticking things into it." >> -- Opus (aka Berkeley Breathed in his "Bloom County" comic strip ) >> >> >> On Tue, Apr 12, 2016 at 6:21 AM, ProfJCNash <profjcnash at gmail.com> wrote: >>> >>>>>>> "The documentation aims to be accurate, not necessarily clear." >>>> I notice that none of the critics >>>> in this thread have offered improvements on what is there. >>> >>> >>> This issue is as old as documented things. With software it is >>> particularly nasty, especially when we want the software to function >>> across many platforms. >>> >>> Duncan has pointed out that critics need to step up to do something. >>> I would put documentation failures at the top of my list of >>> time-wasters, and have been bitten by some particularly weak offerings >>> (not in R) in the last 2 weeks. So .... >>> >>> Proposal: That the R community consider establishing a "test and >>> document" group to parallel R-core to focus on the documentation. >>> An experiment to test the waters is suggested below. >>> >>> The needs: >>> - tools that let the difficulties with documentation be visualized along >>> with proposed changes and the discussion accessed by the wider >>> community, while keeping a well-defined process for committing accepted >>> changes. >>> - a process for the above. Right now a lot happens by discussion in the >>> lists and someone in R-core committing the result. If it is >>> well-organized, it is not well-understood by the wider R user community. >>> - tools for managing and providing access to tests >>> >>> At the risk of opening another can of worms, documentation is an area >>> where such an effort could benefit from paid help. It's an area where >>> there's low reward for high effort, particularly for volunteers. >>> Moreover, like many volunteers, I'm happy to do some work, but I need >>> ways to contribute in small bites (bytes?), and it is difficult to find >>> suitable tasks to take on. >>> >>> Is it worth an experiment to customize something like Dokuwiki (which I >>> believe was the platform for the apparently defunct R wiki) to allow a >>> segment of R documentation to be reviewed, discussed and changes >>> proposed? It could show how we might get to a better process for >>> managing R documentation. >>> >>> Cheers, JN >>> > -- > Sarah Goslee > http://www.functionaldiversity.org > > ______________________________________________ > R-help at r-project.org mailing list -- To UNSUBSCRIBE and more, see > 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.David Winsemius Alameda, CA, USA
Duncan Murdoch
2016-Apr-12 16:58 UTC
[R] 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
William Michels
2016-Apr-12 18:00 UTC
[R] Documentation: Was -- identical() versus sapply()
On Tue, Apr 12, 2016 at 9:44 AM, David Winsemius <dwinsemius at comcast.net> wrote: <SNIP>> > 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. ><SNIP> This sounds like a great opportunity for R-users to contribute to the community (and I certainly would love to participate). One question for R-Core gurus: R-GUIs have the ability to open a script window and use a shortcut to execute code in the R-Console. Can each "Example" on the help pages be configured to do the same? Or at least assist in block-copying to the Console? We'd get a lot more people working through examples that way, and contributors might come up with their own examples to illustrate a particular function. A Dokuwiki site might be a place where people could post and vote on new examples to be included in pre-existing documentation. --Bill William Michels, Ph.D.