I'm working on my first open source R package 📦 and I'm currently working on the docs using #pkgdown. Question for the #rstats community... how do you define **really good** docs? Do you have some examples? #babysfirstRpackage
Comments
Log in with your Bluesky account to leave a comment
CC @statsrhian.bsky.social @nrennie.bsky.social @HeathrTurnr.fosstodon.org.ap.brid.gy @shelkariuki.bsky.social (some R baddies who might have opinions) <3
Depends a bit on what the package does, but generally I like docs with a lot of examples in it (not just the most simple examples). If there's part of examples that happen outside of R, I quite like screenshots/gifs of what should happen when I run the code.
First, be sure to have one or more vignettes; this is a must. Second, make sure that in your man/ pages, not only is the wording clear but also the code examples are clear. The latter will be enhanced by inserting # comments.
I routinely copy things from dplyr: there are pages for specific concepts (non-functions) with inline references across the whole package. Super useful to document bigger packages (with data dictionaries, etc.)! Also, reactable and gt for the huge list of examples!
One thing to consider with pkgdown is that you can have a lot more vignettes than you actually include in your package. CRAN wont let you have vignettes that take a lot of time to build. So this can reduce the utility of vignettes or force you to do some tedious stuff to pre-run things and include
those pre-generated results as data files that your vignettes read in. These data files can count against your package size. So what I do is I have vignettes that show up on the package down site but I strip them out before I submit to CRAN.
Comments
I like the help files in a function to be fairly minimal without too much complex code set up.
I often find myself referring to the worked example in {reactable} and the casestudies in {gt}
https://glin.github.io/reactable/articles/examples.html#row-names-and-row-headers
https://gt.rstudio.com/articles/case-study-gtcars.html
It's extensive but clear & well organised: functions references + articles on specific topics that make things easy to find + easy to check NEWS file.
(It's not an R package, but Quarto docs are also seriously good: https://quarto.org/)