Improving package documentation

[leeper]

R documentation is pretty good, but package documentation is often really incomplete (to the point of just enough to pass R CMD check). Some would argue that roxygen helps here, but that really solves a different problem (in-line documentation) rather than enhancing documentation completeness.

Can we do anything to help improve the process of writing docs? Maybe:

• Additional documentation checks, such as:
  • Whether a package-level documentation page has been created
  • Whether functions are cross-referenced
  • Whether examples are actually present
  • Whether descriptions and argument definitions are coherent
• Manuals to teach documentation writing
• A gallery of exemplar documentation examples
• Tools to facilitate thorough documentation (in roxygen or Rd format)
• Templates that help to create better, more complete, and more useful documentation

Or ways of encouraging users to contribute to documentation? Beginners can actually be very good contributors to docs because they're relying on them more than experienced package users, so how can we design systems to integrate beginnners' efforts into R package development projects?

[smbache]

+1 I like this idea: perhaps encourage usage with a badge ;)

[jennybc]

👍 rOpenSci has had a lot of relevant internal discussion about this, so we can probably transfer some notes and concrete ideas into this thread.

As @leeper points out, this also has obvious ties to initiatives to create on-ramps for newcomers. Which I think has a disproportionate benefits for under-represented groups. Which is also good.

[gaborcsardi]

I like this very much, too. As for the check and badge, I started writing a 'good practice' package, that will definitely include similar checks to what you suggest: ropensci-review-tools/goodpractice#1
But it might also make sense to have a smaller package that only deals with docs.

I like the rest as well, i.e. templates, etc. There is an "awesome" README collection, btw: https://github.com/matiassingers/awesome-readme
We could make a similar that is R package specific.

As for beginners, if you develop on GH, you can create a "beginner-friendly" label for issues, to mark the ones that are good for people learning the system. We can also have some central location for these, maybe.

[smbache]

Speaking of good practice, I've often thought about (and wanted) a managed style guide which could serve as a bigger and more official reference than the many small style guides found in various book chapters etc. how about an ROpenStyle ? :)

[sckott]

we do have https://github.com/ropensci/packaging_guide - but it's not exhaustive

[leeper]

Another idea I've been playing around with in MTurkR is tutorial-style documentation pages. Here's an example: https://github.com/leeper/MTurkR/blob/master/man/UseCaseSurvey.Rd

These are in addition to function pages and are meant to show how to achieve a common use case in an extended, annotated example.

Downside is this is fairly time consuming to write, but maybe could be made easier with something like maxygen.

[gaborcsardi]

@leeper Isn't it just simpler to write vignettes for tutorials? I think this is what they are for. Rmd is great for tutorials imo.

OTOH it bothers me a bit that the vignettes are not part of the regular R docs, and maybe maxygen/roxygen can indeed help with this. It could just generate an Rd from the md output of knitr. Would that make sense?

[leeper]

The Rd format fully supports these kind of tutorials (the regex page in the base package being a pretty good example), so I think they can be useful. Vignettes are not part of the regular docs, which is a problem: it becomes awkward to link to code docs from vignettes and vice versa.

It's nice that vignettes show up on CRAN but once installed most people lose track of them. And if people are using devtools to install in the first place, they're probably not building the vignettes anyway.

[gaborcsardi]

Rd supports a lot of things, but it is still a pain to write, especially if you want to run the code in the Rd, show output, etc.

Yes, I agree that it is confusing that vignettes are not part of the "regular" R docs. So how about some automatic Rmd vignette -> Rd docs conversion? Much the same way as Roxygen for the "regular" docs. Once maxygen is merged into Roxygen, it will be a piece of cake to implement it.

[leeper]

Ooh, I like that idea. Write everything in Rmd, then during devtools::document(), the vignettes could be installed as Rd files, as well. Perhaps it would make sense to leverage the "dynamic page" features of Rd.

[gaborcsardi]

The dynamic Rd is great for small things, but personally I would not use that to run the whole Rmd, I think knitr is more reliable for that, just like it is superior to Sweave.

They do have a stage argument, though, to control when to run the code, and we can use that to run code when the Rd page is being installed or rendered. If we need something like this.

Anyway, I would be more than happy to flash this out, and even implement it during the unconf, if you want to do some coding on the spot. :) I do have a roxygen branch with maxygen included, just need to make sure that it still works with the latest roxygen updates. We could use that for a prototype.

[jennybc]

A side benefit of what you propose basically addresses my concern that (compiled) vignettes have no good workflow or home during development, i.e. between CRAN releases: r-lib/devtools#931. If they got compiled to Rd, then at least they'd be as available as the help files.