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

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

On 12/04/2016 11:30 AM, ProfJCNash wrote:
> 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.
I don't think I can.  I don't intentionally write obscure documentation,
so I think they're all clearly written.

Which leaves the problem of choosing one.  I could probably generate a 
list of help pages where I've contributed enough
to be comfortable editing them, but you'll need to choose which one to fix.

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

If you generate the list of pages you're comfortable editing, the posse
of folk who have already come forward can select one that we think can
be improved and see how we get along with it.

Sarah has already noted that Github offers wiki documentation. It is
likely imperfect, but we can (and should!) get a bit of experience to
learn where the important issues lie.

Thanks, JN

On 16-04-12 01:53 PM, Duncan Murdoch wrote:
> On 12/04/2016 11:30 AM, ProfJCNash wrote:
>> 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.
> 
> I don't think I can.  I don't intentionally write obscure
documentation,
> so I think they're all clearly written.
> 
> Which leaves the problem of choosing one.  I could probably generate a
> list of help pages where I've contributed enough
> to be comfortable editing them, but you'll need to choose which one to
fix.
> 
> Duncan
>>
>> 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
>