The R Documentation Task Force: The Next Generation R Documentation System by Joseph Rickert and Hadley Wickham.
From the post:
Andrew Redd received $10,000 to lead a new ISC working group, The R Documentation Task Force, which has a mission to design and build the next generation R documentation system. The task force will identify issues with documentation that currently exist, abstract the current Rd system into an R compatible structure, and extend this structure to include new considerations that were not concerns when the Rd system was first implemented. The goal of the project is to create a system that allows for documentation to exist as objects that can be manipulated inside R. This will make the process of creating R documentation much more flexible enabling new capabilities such as porting documentation from other languages or creating inline comments. The new capabilities will add rigor to the documentation process and enable the the system to operate more efficiently than any current methods allow. For more detail have a look at the R Documentation Task Force proposal (Full Text).
The task force team hopes to complete the new documentation system in time for the International R Users Conference, UseR! 2017, which begins July 4th 2017. If you are interested in participating in this task force, please contact Andrew Redd directly via email (andrew.redd@hsc.utah.edu). Outline your interest in the project, you experience with documentation any special skills you may have. The task force team is particularly interested in experience with documentation systems for languages other than R and C/C++.
OK, I have a weakness for documentation projects!
See the full proposal for all the details but:
…
There are two aspects of R documentation I intend to address which will make R an exemplary system for documentation.The first aspect is storage. The mechanism of storing documentation in separate Rd files hinders the development process and ties documentation to the packaging system, and this need not be so. Life does not always follow the ideal; code and data are not always distributed via nice packages. Decoupling the documentation from the packaging system will allow for more dynamic and flexible documentation strategies, while also simplifying the process of transitioning to packages distributed through CRAN or other outlets.
The second aspect is flexibility of defining documentation. R is a language of flexibility and preference. There are many paths to the same outcome in R. While this has often been a source of confusion to new users of R, however it is also one of R’s greatest strengths. With packages flexibility has allowed for many contributions, some have fallen in favor while others have proven superior. Adding flexibility in documentation methods will allow for newer, and ideally improved, methods to be developed.
…
Have you seen the timeline?
- Mid-August 2016 notification of approval.
- September 1, 2016 Kickoff for the R Documentation Task Force with final members.
- September 16, 2016 Deadline for submitting posts to the R-consortium blog, the R-announce, Rpackage-devel, and R-devel mailing lists, announcing the project.
- September 1 through November 27th 2016 The task force conducts bi-weekly meetings via Lync to address issues in documentation.
- November 27th, 2016 Deadline for preliminary recommendations of documentation extensions. Recommendations and conflicts written up and submitted to the R journal to be published in the December 2016 issue.
- December 2016 Posts made to the R Consortium blog, and R mailing lists to coincide with the R Journal article to call for public participation.
- January 27, 2017 Deadline for general comments on recommendations. Work begins to finalize new documentation system.
- February 2017 Task force meets to finalize decisions after public input.
- February-May 2017 Task force meets monthly as necessary to monitor progress on code development.
- May 2017 Article is submitted outlining final recommendations and the subsequent tools developed to the R Journal for review targeting the June 2017 issue.
- July 4-7, 2017 Developments will be presented at the International R users conference in Brussels, Belgium.
A very ambitious schedule and one that leaves me wondering if December of 2016 is the first opportunity for public participation, will notes/discussions from the bi-weekly meetings be published before then?
Probably incorrect but I have the impression from the proposal that documentation is regarded as a contiguous mass of text. Yes?
I ask because the “…contiguous mass of text…” model for documentation is a very poor one.
Documentation can present to a user as though it were a “…contiguous mass of text…,” but as I said, a very poor model for documentation itself.
Imagine R documentation that automatically updates itself from R-Bloggers, for example, to include the latest tutorials on a package.
Or that updates to include new data sets, issued since the last documentation update.
Treating documentation as though it must be episodically static should have been abandoned years ago.
The use of R and R development are not static, why should its documentation be?