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 your future self want to know in order to quickly understand what is going on in the project?

This is what needs to be described in the README file. It should be the primary entry point into your project, the place where new users go first to get an orientation.

There is no common standard how to structure a README file, but you should usually provide at least the following information, structured by sections:

Name and Description

• How is the project called?
• What is it about?
• Which files does the project folder contain?
• How are they organized?

Data

• Are any (empirical) data involved (e.g., being analyzed or used as input)?
• Are they already included in the project folder? If not: From which sources can they be obtained?
• Where is their data dictionary located?
• Which terms, usage restrictions, or licenses apply?
• (optionally) If they are not publicly available, is an alternative, synthesized version provided?

Computational Requirements / Dependencies

• What software needs to be installed to run the analysis?

For every dependency (e.g., packages that you load in R), describe where it can be obtained from. If the code has particular hardware requirements (e.g., in terms of processor or memory), these should be also noted. Finally, for steps that take more than a couple of seconds, indicate the approximate runtime.

For an R project, the most important information for enabling reproducibility are the specific version of R and the loaded packages. Ideally, you also list other system dependencies. The in-depth supplementary material Identify additional system dependencies for the README provides more information on determining the dependencies of an R project. For the purpose of this tutorial, however, you can skip this step.

How to reproduce the results

• Provide step-by-step instructions that are necessary to reproduce all reported results.

Is there a master script or a particular order in which any scripts need to be executed?

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?

Identifying R Dependencies

If you just write “We used R to analyze the data” in your manuscript or in the Computational Requirements / Dependencies section of your README file, this would be too underspecified. To enable someone else to really reproduce your results, you need specific information on …

• The exact version of R
• All packages and their versions that you loaded in your project
• (optionally) Further system dependencies

R & Package Dependencies

R itself and the R packages are already documented as our tutorial project uses renv: The information is stored in the renv.lock file at the root of the project, which tracks each package’s version and source. In this case, you can simply refer to that in the README file and all is done.

If your project has no renv.lock file, you can still use renv together with the package sessioninfo to get an overview of all used packages and their versions:

R Console

sessioninfo::session_info(pkgs = unique(renv::dependencies()$Package))

You can copy & paste that information into your README file.

Practical Exercise: Create your README!

Create your README now as the file README.md, located at the top level folder.

If you feel stuck, you can have a look at the following examples:

Tip 1: Name and Description

README.md

# Penguin Paper

This project contains the Quarto manuscript of our study on penguins ("Manuscript.qmd"). It is written in R and uses `renv` to track its dependencies.

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 `data_dictionary.qmd`

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

Tip 2: Data

README.md

## Data

The manuscript analyzes the "palmerpenguins" data set available from <https://cran.r-project.org/package=palmerpenguins>. The data is stored as "data.csv" and documented in the file "data_dictionary.html". It is made available under CC0 1.0.

Tip 3: Computational Requirements

README.md

## Computational Requirements

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 command, which should install all required R packages at their recorded versions:

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

Tip 4: How to reproduce the results

README.md

## How to reproduce the results

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

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

Tip 5: Citation

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.

Tip 6: License

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/). For further copyright information, see `LICENSE.txt`.

After adding a README, commit your changes:

Terminal

git status
git add .
git commit -m "Add README"