Make a README

What does a README contain?

Once you have prepared your project and 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? Is there a published article associated with it?
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? Mention all dependencies here that are not explicitly managed by renv, such as the system dependencies of R packages as well as the version of Quarto. An R package’s system dependency is any additional software that you need to install on your computer in order to use a particular R package. For example, the R package reticulate allows to run Python code from within R. However, in order to actually use it, one has to additionally install Python itself as it does not come together with reticulate – rather, it is a system dependency. See Section 2 for additional information.
Usage: Which files does the project 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? We recommend to increase citability by using the CodeMeta generator to create a file called codemeta.json. Alternatively, one can also use the R package codemetar to create this file. Then, put it into the project folder. Another common standard is the Citation File Format (CFF), which is an equally valid option.
License: Under which license are the contents in this project 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 in the current project:

Console

pak::pkg_sysreqs(renv::dependencies()$Package)

The output may look like the following:

── Install scripts ─────────────────────── 
dnf install -y make pandoc

── Packages and their system dependencies 
fs        – make
knitr     – pandoc
rmarkdown – pandoc
sass      – make

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

Terminal

make --version
pandoc --version

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:¹

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

Create It!

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

Tip 1: Name

README.md

# Penguin Paper

Tip 2: Badges/Project Status

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)

Tip 3: Description

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.

Tip 4: Installation/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 directory of this project and run the following, which should install all required R packages at their recorded versions:

```r
renv::restore()
```

Tip 5: Usage

README.md

## Usage

The most important file in this project 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 created using `write.csv(palmerpenguins::penguins, "dat.csv", row.names = FALSE)`
- `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
```

Tip 6: Citation

README.md

## Citation

Please cite this draft as follows:

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

Tip 7: License

README.md

## License

The manuscript file and the bibliograhpic references are made available by us under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). The data set by Kristen Gorman has been published under [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/). `apaquarto` has also been published under [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/). All other files in this project are available under [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/).

Footnotes

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