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

[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