> On Apr 12, 2016, at 8:31 AM, Sarah Goslee <sarah.gos...@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.4...@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 <profjcn...@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@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 ______________________________________________ R-help@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.
