[R] Documentation: Was -- identical() versus sapply()

[David Winsemius]

> 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