Rmarkdown version of toplevel README no longer necessary?

[hlapp]

As a remnant from earlier when there wasn't a package website created from vignettes and documentation, the top-level README is still a Rmarkdown document, from which README.md is generated. The Rmarkdown version of the README still contains a number of code chunks, but these are either expressly precluded from evaluation, or not included in the markdown generation to start with. As they should be, because no code to be evaluated is demonstrated in the README anymore.

This will probably not change in the future, i.e., new functionality will presumably also end up documented in vignettes and function documentation blocks, rather than advertised in the README.

If we are in agreement on this, then there's no need anymore for the Rmarkdown version of the README anymore, right?

[cboettig]

That's a good question. On the other hand, Rmd README (with executable R chunks) are nearly universal in mainstream R packages, so another way of looking at this is that we have been a bit too curt in our current README, and not followed the best practice in which we can illustrate a compelling and simple use case for the package on the "first page."

For instance, we could probably show a minimal example illustrating nexml_read() and nexml_write() on the readme (and thus on the pkgdown homepage)? Currently someone coming to the README or pkgdown looking for a quick start on the package if faced with a page of text and no examples, followed only by the advice to go read more documentation....

[hlapp]

On the other hand, Rmd README (with executable R chunks) are nearly universal in mainstream R packages

So is this because most mainstream R packages aren't using a pkgdown-generated website yet and/or don't have a "Getting started" vignette, or because it's really a best practice regardless?

I mean, the link "Get started" is right there if you do have both of these (as RNeXML now does) 😊

[cboettig]

I think the latter. Most have a pkgdown site but also have a getting started on the readme. I think the idea is that the readme should let you 'get started' and run something, a README is the universal "start here". So I think it's not ideal to instead present a page of text and then another link that says "no, actually get started here".

Packages in https://github.com/r-lib are a nice benchmark for this (also most ropensci packages), where READMEs follow a common format of "installation", "usage" , and then "motivation" or something similar.

[rvosa]

I would vote to not have an Rmd file. Reasons:

• I was not aware this being a practice at all; I've never looked at a README.Rmd of any package; it won't show up when you pull up any documentation in RStudio or whatever
• We create the risk of partial duplication of code samples; things going out of sync; bad documentation becoming worse than no documentation
• More generally speaking I don't think READMEs are used for code samples, but rather as the most basic top-level set of pointers to licenses, installation instructions, documentation, credits, etc.

(...and the main reason is of course general laziness and work avoidance...)