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