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? 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.

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? Is there a published article associated with it that you would like to have cited? 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 licenses are the works 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 the current project directly depends on:

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

# Then, identify the system dependencies
# of your direct dependencies.
renv::dependencies()$Package |>
  unique() |>
  pak::pkg_sysreqs()

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. Often, 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: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 directory 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 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
```
README.md
## Citation

Please cite this draft as follows:

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

The manuscript file and the bibliographic 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/).
Back to top

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.↩︎