R help - Apr 2016 - Documentation: Was -- identical() versus sapply()

>>>> "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

On 12/04/2016 9:21 AM, ProfJCNash 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.
The idea of having non-core people write and test documentation appeals 
to me.   The mechanism (Dokuwiki or whatever) makes no difference to me; 
it should be up to the participants to decide on what works.

The difficulty will be "calibration":  those people need to make
changes
that core members agree are improvements, or they won't be incorporated.

I'd suggest that you start very slowly.  First choose *one* help page 
that you think needs improvement, and explain why to one of the authors 
of that page, and what sort of improvements you propose to make.  Then 
get  the author to agree with the proposal, do it, and get the same 
author to agree to the final version and commit it.

I'll volunteer to participate in the approval and committing stage, but 
at first only for pages that I authored.  If it turns out to be an 
efficient way to improve docs, then I'd consider other pages too.

Duncan Murdoch

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
>
> ______________________________________________
> 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.

Thanks Duncan, for the offer to experiment.

Can you suggest a couple of your pages that you think might need
improvement? We might as well start with something you'd like looked at.

Then I'll ask if there are interested people and see what can be done
about getting a framework set up to work on one of those documents.

JN


On 16-04-12 10:52 AM, Duncan Murdoch wrote:
> On 12/04/2016 9:21 AM, ProfJCNash 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.
> 
> The idea of having non-core people write and test documentation appeals
> to me.   The mechanism (Dokuwiki or whatever) makes no difference to me;
> it should be up to the participants to decide on what works.
> 
> The difficulty will be "calibration":  those people need to make
changes
> that core members agree are improvements, or they won't be
incorporated.
> 
> I'd suggest that you start very slowly.  First choose *one* help page
> that you think needs improvement, and explain why to one of the authors
> of that page, and what sort of improvements you propose to make.  Then
> get  the author to agree with the proposal, do it, and get the same
> author to agree to the final version and commit it.
> 
> I'll volunteer to participate in the approval and committing stage, but
> at first only for pages that I authored.  If it turns out to be an
> efficient way to improve docs, then I'd consider other pages too.
> 
> Duncan Murdoch

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