Make a README

What Does a README Contain?

Having settled on a license, it is time to add a final touch. Imagine returning to your project in five years, having forgotten most of the details of what you did exactly. What would be useful to know in order to quickly understand what is going on in the project? This is what needs to be described in the README. While you could just start writing along, most READMEs have some sections in common which we describe below.

Name

How is the project called?

Badges/Project Status

Badges typically report quick facts, like whether the project is actively maintained, how many dependencies it has, or whether it has been published in a package repository. Sometimes, the license, any associated DOIs, or quality metrics like code coverage by unit tests are communicated via badges as well.

Description

What is the project about? What are its features? Why was it created?

Visuals

Is there anything you can show that demonstrates how the project can be used? Screenshots or other visuals can make the README more appealing.

Installation/Dependencies

What steps need to be taken to run the project? What software needs to be installed? R itself and the R packages are already documented as this project uses renv. Therefore you can focus on all other dependencies, such as the system dependencies of R packages as well as the version of Quarto.1 Also, don’t forget to mention software that you have used for any manual steps. See Section 2 for additional information. It may make sense to provide these information in the README even if you already cite all programs and their version numbers in your manuscript.

Usage

Which files does the project folder contain? How are they organized? How can one run the project – is there a master script or a particular order in which any scripts need to be executed? How long does it take to run all scripts? Is there additional documentation available?

Support

Do you offer support or help, for example, via GitHub discussions or a mailing list?

Contributing

If the project is active: Can other people contribute? How? Do you accept contributions? Do you review issues? This section is sometimes outsourced into a file called CONTRIBUTING.md.

Authors

Who was involved in creating this project? This involves you, your co-authors, and anybody you accepted contributions from.

Citation

Is there a recommended way to cite this project? Is there a published article associated with it that you would like to have cited?

License

Under which licenses are the works in this project folder available?

Installation/Dependencies

An overview over the system dependencies of R packages can be created using the function pak::pkg_sysreqs(). In combination with renv, we can obtain the system dependencies of all R packages the current project directly depends on:

Console
# First, install pak
renv::install("pak")

# Find all dependencies
deps <- renv::dependencies()$Package |>
   unique() |>
   pak::pkg_deps(dependencies = NA) |>
   getElement("package")

# Identify the system dependencies
pak::pkg_sysreqs(deps)

The output may look like the following:

Finding R package dependencies ... Done!
── Install scripts ──────────────────────── Fedora 40 ── 
dnf install -y make pandoc libcurl-devel \
  openssl-devel libicu-devel v8-devel libxml2-devel \
  git

── Packages and their system dependencies ──────────────
blastula  – pandoc
curl      – libcurl-devel, openssl-devel
fs        – make
knitr     – pandoc
openssl   – openssl-devel
remotes   – git
rmarkdown – pandoc
sass      – make
stringi   – libicu-devel
V8        – v8-devel
xml2      – libxml2-devel

We can see that the programs make, pandoc, and git were identified as system dependencies. Often, one can obtain their version by running them with the --version argument:

Terminal
make --version
pandoc --version
git --version

The other system dependencies are libraries, and the method to identify the installed version varies between operating systems. For example, on Fedora Linux, one can run the following:

Terminal
rpm -q libcurl-devel openssl-devel libicu-devel v8-devel libxml2-devel

However, they are only relevant if the R packages were installed from source, rather than as binary package.

We also know that we need Quarto to create the PDF, so let’s find out its version as well:

Terminal
quarto --version

If you installed apaquarto or any other Quarto extension, one can query their versions as follows:2

Terminal
quarto list extensions

Finally, we know that we installed a \(\TeX\) distribution to create the PDF, so let’s find out its version by running:

Terminal
quarto check

The output is quite long and it might look slightly different for you, but the relevant sections are the following:

[✓] Checking tools....................OK
      TinyTeX: v2024.09
      Chromium: (not installed)

[✓] Checking LaTeX....................OK
      Using: TinyTex
      Path: /home/r155953/.TinyTeX/bin/x86_64-linux
      Version: 2024

Of course, all the system dependencies identified until now may have dependencies on their own. Use your own judgement to decide when not to dig deeper.

Create It!

Create your README now as the file README.md. If you feel stuck, you can have a look at the following examples:

README.md
# Penguin Paper
README.md
[![Project Status: Unsupported – The project has reached a stable, usable state but the author(s) have ceased all work on it. A new maintainer may be desired.](https://www.repostatus.org/badges/latest/unsupported.svg)](https://www.repostatus.org/#unsupported)
README.md
This project contains the Quarto manuscript of our study on penguins. It is written in R and uses `renv` to track its dependencies.
README.md
## Dependencies

This manuscript requires the following system software to be installed. In addition, we provide the version numbers this manuscript has last been run with:

- [Quarto](https://quarto.org/docs/download/) 1.6.9
- GNU Make 4.4.1
- Pandoc 3.3
- TinyTeX 2024.09
- [R](https://cloud.r-project.org/) 4.4.1

On Fedora Linux, Make and Pandoc can be installed as follows:

```bash
dnf install -y make pandoc
```

Quarto and R can be installed using the links provided. TinyTeX can be installed using Quarto by entering the following into the terminal:

```bash
quarto install tinytex
```

All R packages that this project requires are managed using [`renv`](https://cran.r-project.org/package=renv). Therefore, `renv` needs to be installed first, by entering the following in the R console:

```r
install.packages("renv")
```

Next, one can open a new R session in the root folder of this project and run the following, which should install all required R packages at their recorded versions:

```r
renv::restore()
```
README.md
## Usage

The most important file in this project folder is `Manuscript.qmd` which contains the text of the article as well as the code for its computations. It is accompanied by the following files:

- `Bibliography.bib`: bibliographic references used in the manuscript
- `data.csv`: a data set containing the simplified `palmerpenguins` data
- `data_dictionary.html`: a dictionary to the data file, created using `create_data_dictionary.R`

The folder `_extensions` contains the `apaquarto` extension which is used to typeset the PDF accoording to APA guidelines.

The manuscript can be rendered to PDF using the following command:

```bash
quarto render Manuscript.qmd
```

You need to add your name in the following example:

README.md
## Citation

Please cite this draft as follows:

> Zerna, Scheffel, & <YOUR NAME> (2024): "A Study on Penguins: A Minimal Reproducible Example". Unpublished manuscript.

Of course, you would use the same license for the manuscript that you chose in the previous step. You need to add your name in the following example:

README.md
## License

The manuscript files `Manuscript.qmd`, `Manuscript.tex`, and `Manuscript.pdf` by Josephine Zerna, Christoph Scheffel, and <YOUR NAME> are available under [CC\ BY-SA\ 4.0](https://creativecommons.org/licenses/by-sa/4.0/) or (at your option) under the [AGPLv3](https://www.gnu.org/licenses/agpl-3.0.html) (or later). For further copyright information, see `LICENSE.txt`.

Footnotes

  1. As of August 2024, a proposal for renv to record the version of Quarto has not been implemented, see rstudio/renv#1143.↩︎

  2. Luckily, the extensions are included in the project folder, so technically their version is already recorded in the project’s files.↩︎