Code and Applications

How to write a README

When collecting data, essential information on datasets, such as how variables were measured or how missing values were handled, is often only recorded in field notebooks or a researcher’s memory, and it can be easily lost over time. Good documentation makes it easier for others (and you!) to understand the dataset.

One important way to document data is through a README file. A README is a human-readable document, often a .txt file, that provides a narrative description of the dataset, including its purpose, structure, and how it should be used. A well-structured README is the first step toward clear and reusable data documentation, and it can serve as a foundation for more formal metadata standards.

There is a lot of variation in how people choose to write README files, so this blog post aims to provide a short guide for what makes a good README file.

What should be in a good README?

  • A clear description of the data and, if relevant, the publications it is associated with, any authors of these publications and their ORCIDs where possible.
  • Contact details of at least one author, including their ORCID.
  • License information. Note that this should also be provided as a separate LICENSE file.
  • Recommended citation for the data, ideally also include a dedicated CITATION.cff file.
  • Detailed contributions to the data, following CRediT taxonomy.
  • A concise description of which data files are needed to reproduce specific analyses/figures/tables in any associated papers, and any proprietary software required.
  • A brief, but specific, summary of how the data were collected, from where, and when (as appropriate).
  • Sources of data if it was from a literature review.
  • A list of all data files, whether they contain raw or processed/cleaned/ summarised data, and briefly what they contain, e.g. life history variables.
  • Column-by-column description of the data files, along with column headers, measurement units, allowed options for categorical variables, reference schemes for controlled vocabulary, explanations of any abbreviations, identifiers that relate observations across separate data files, and missing-data codes.
  • You should also have a README for your code, or one for the code and data combined. You should refer to any scripts used to process your data, and what these processing steps involve. You should also include lists of key packages and software tools used to run your code in the README. See BES Reproducible Code guide.

Example of a good README

Your README may look different but should contain this sort of information.

———-

README: Data for my awesome paper

Author(s): Me and my colleagues (me@myinstitution.ac.uk)

This repository contains all the data used in “My Awesome Paper” [link to published version]. Shared under a CC0 license.

To cite the paper:

Me and my colleagues. 2026. My Awesome Paper. Methods in Ecology and Evolution, 100: 1-10, DOI: [doi for paper].

To cite this dataset:

Me and my colleagues. 2026. Data from: My Awesome Paper v1.0. Zenodo. DOI: [doi for data].

Data collection and processing (in brief)

[A brief description of how the data were collected]

All datasets use “NA” for missing data.

Raw data

1. 2026-01-01_data-on-plants.csv

Contains all the data we collected on plants.

Column headers are as follows:

  • species. Species binomial name.
  • date. In YYYY-MM-DD format.
  • growth_form. Categorical. Options are: Tree, Shrub, Vine, or Herb.
  • prop_cover. Proportion of quadrat covered by plant. Values between 0 and 1.

2. 2026-01-01_data-on-animals.csv

Contains all the data we collected on animals.

Column headers are as follows:

  • species. Species binomial name.
  • number_legs. Number of legs. Count.
  • observation_height. Categorical. B = below ground; G = on the ground; T = in a tree.
  • length_mm. Length of the animal from snout to vent in mm.

Processed/cleaned data used in analyses

1. 2026-02-01_cleaned-data-on-plants-and-animals.csv

This is the cleaned dataset used in all analyses and to produce figures 1-3 and table 1. Script 1 of our code takes raw datasets 1 and 2, corrects the taxonomy, adds _ between Genus_species for the species names, removes errors in counting the numbers of legs, and then combines the plant and animal datasets.

Column headers are as follows:

  • species. Species binomial name in the form Genus_species.
  • growth_form. Categorical. Options are: Tree, Shrub, Vine, or Herb
  • prop_cover. Proportion of quadrat covered by plant. Values between 0 and 1.
  • number_legs. Number of legs. Count.

number_individuals. Number of individuals in the survey area. Count.


Help with writing a README file

There are several great tools, guides and templates for the creation of README files. These include the McMaster University README Generator and READMEBuilder.

This blog post is based on the BES Guide to Data Management. This is a great and free resource, providing further info on good data management practices. Read here. A big thanks to everyone who contributed to the guide, and specifically Antonio J. Pérez-Luque who wrote the section on documenting data.

Leave a Reply