Documentation: Was -- identical() versus sapply()

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