R Packages, 2nd Edition

Chapter 18. Other Markdown Files

In this chapter we highlight two files that are conventionally used to provide some package-level documentation. These two are important, because they are featured on both the CRAN landing page and the pkgdown site for a package:

• README.md, which describes what the package does (see “README”). The README plays an especially important role on GitHub or similar platforms.

• NEWS.md, which describes how the package has changed over time (see “NEWS”).

Even if your package is intended for a very limited audience and might not ever be released on CRAN, these files can be very useful. These two files don’t have to be written in markdown, but they can be. In keeping with our practices for help topics and vignettes, it’s our strong recommendation and it’s what we describe here.

README

First, we’ll talk about the role of the README file and we leave off the file extension, until we’re ready to talk about mechanics.

The goal of the README is to answer the following questions about your package:

• Why should I use it?

• How do I use it?

• How do I get it?

The README file is a long-established convention in software, going back decades. Some of its traditional content is found elsewhere in an R package; for example, we use the DESCRIPTION file to document authorship and licensing.

When you write your README, try to put yourself in the shoes of someone who has come across your package and is trying to figure out if it solves a problem they have. If they ...