README¶

Overview

This is the README page, part of Essentials in the A-LIFE RDM GEMs collection.

This page explains what a README file is, why it matters, and provides a template and guidance to get started:

What is a README, and why include one?
Best Practices for a Good README File
What to Include in a README
README Template — Get Inspired
Examples from A-LIFE Researchers

Supporting materials: Yoda - Metadata and Documentation, RD - Documentation, Zenodo - Documentation
Authors: Irene Martorelli, Brett Olivier — Last modification: 2026-08-02 — Version: 0.3.1

What is a README, and why include one?¶

A README is a plain text file (.md or .txt) included with your dataset that describes its content. It is the first thing someone should read when they access your data — think of it as the cover page and table of contents for your dataset.

A README is not a Yoda or Zenodo-specific requirement: it is a universal best practice that applies to any folder or data package, regardless of where it is stored. A README written during your active project in Research Drive can be transferred directly into Yoda or Zenodo without modification when you archive your data.

Why include one?

Makes your dataset understandable to others — and to your future self
Required or strongly recommended by most repositories (Zenodo, Yoda)
Supports the FAIR principles — Findable, Accessible, Interoperable, Reusable
Reduces the number of questions you receive from people trying to reuse your data
Ensures continuity when collaborators change or projects are revisited years later

Best Practices for a Good README File¶

The following best practices are adapted from the Cornell Data Services README guide — our top recommendation for writing READMEs for research data.

Write in plain text — use .md or .txt format; avoid proprietary formats like Word
One README per logical cluster of files — a single README can cover multiple related files; create separate READMEs for unrelated datasets
Name it clearly — use README.md or README.txt so it is immediately visible and recognisable
Place it at the root of the data package folder so it is the first file anyone sees
Use standardised date formats — YYYY-MM-DD (ISO 8601) throughout
Be consistent — if you have multiple READMEs across a project, use the same structure and terminology in each

What to Include in a README¶

Highly recommended

Cornell Data Services — Writing READMEs for Research Data — the most complete and practical README guide available, with a downloadable template adapted for research data reuse. We strongly recommend bookmarking this page.

The sections below follow the structure recommended by Cornell Data Services¹. Fields in bold are the minimum recommended for data reuse.

General information

Dataset title
Authors — names, affiliations, ORCID identifiers; include principal investigator and contact person
Date of data collection — single date or range in YYYY-MM-DD format
Geographic location of data collection (if applicable)
Funding sources

Data and file overview

For each file or folder: a short description of what it contains
File format (if not obvious from the extension)
Relationships between files (e.g. which script processes which data file)
Date the file was created; date(s) of updates and what changed

Sharing and access information

Licence — the licence that applies to the data
Links to related publications that cite or use the data
Recommended citation for the dataset

Methodological information

Description of data collection or generation methods — link to protocols or publications where relevant
Data processing steps — how raw data was cleaned, transformed, or analysed
Software, instruments, and version numbers needed to open or run the files
Quality assurance procedures performed on the data

Data-specific information (repeat for each file or dataset as needed)

Variable list — full names and definitions of all column headings for tabular data
Units of measurement
Codes for missing data (e.g. NA, -999, null)
Specialised formats, abbreviations, or categorical codes used

README Template — Get Inspired¶

The template below is written in Markdown (.md) — a lightweight plain text format that renders nicely in most tools (GitHub, VS Code, data repositories, etc.). You do not need to know Markdown to use it: copy the template into any text editor and fill in your information. Not all sections will apply to every project — remove what is not relevant and expand what matters most for your data.

Tip

Use the copy button (top right of the code block) to copy the full template to your clipboard in one click.

# README — [Dataset Title]

## General information

**Title:** [Dataset title]
**Authors:**
- Name, Affiliation, ORCID
- Name, Affiliation, ORCID

**Principal investigator / contact:** [Name, email]
**Date of data collection:** YYYY-MM-DD (or YYYY-MM-DD / YYYY-MM-DD)
**Geographic location:** [Location, if applicable]
**Funding:** [Funding agency and grant number, if applicable]

---

## Data and file overview

| File / Folder     | Description                    | Format      | Created    |
|---|---|---|---|
| `data/raw/`       | Raw instrument output          | .csv        | YYYY-MM-DD |
| `data/processed/` | Cleaned and processed data     | .csv        | YYYY-MM-DD |
| `scripts/`        | Analysis scripts               | .py / .R    | YYYY-MM-DD |
| `results/`        | Output figures and tables      | .png / .csv | YYYY-MM-DD |
| `README.md`       | This file                      | .md         | YYYY-MM-DD |

---

## Sharing and access information

**Licence:** [e.g. CC BY 4.0 — see LICENCE.txt for full terms]
**Related publication:** [Title, DOI]
**Recommended citation:** [Authors (Year). Title. Repository. DOI]

---

## Methodological information

**Data collection methods:**
[Brief description of how data was collected — instruments, protocols, experimental conditions]

**Data processing:**
[How raw data was cleaned, processed, or transformed]

**Software and dependencies:**
- [Software name, version]
- [Language: e.g. Python 3.11, R 4.3]

---

## Data-specific information

### [Filename or dataset name]

**Number of variables:** [N]
**Number of rows / observations:** [N]

| Variable | Full name   | Description | Units | Missing values |
|---|---|---|---|---|
| `col1`   | Column one  | Description | unit  | NA             |
| `col2`   | Column two  | Description | unit  | NA             |

[Repeat for each file as needed]

A community-inspired template

This template was shaped by the interactions and support given to A-LIFE researchers over time. The questions asked, the datasets shared, and the feedback received from the A-LIFE community were invaluable in understanding what works in practice — and what researchers actually need when documenting their data. Thank you to everyone who contributed, knowingly or not, to making this resource better.

Tips for a good README

Write it before you upload — it forces you to think about what you are sharing and why
Copy the key description into the Zenodo or Yoda Description field so it is visible on the landing page
Include the README inside your ZIP archive and also upload it as a separate file
Use YYYY-MM-DD date formats throughout for consistency

Examples from A-LIFE Researchers¶

Get inspired by your A-LIFE colleagues!

Not sure where to start? Browse the README files from these published A-LIFE datasets — see how colleagues structured their documentation and adapt it to your own dataset and workflow. Every research domain is different, so feel free to mix and match what works best for you.

Yoda publications

Feral Swine Selective Sweep — Barmentlo, Niek (2024) · DOI · View README in Vault

Data from: "Distinct modulatory effects of high-fiber and fermented-food diets on gut microbiota, immune function, transit time, and sleep quality in a citizen science randomized controlled trial" — van den Belt, Maartje; van de Put, Marieke et al. (2025) · DOI · View README in Vault

Nocturnal and grounded carabid beetle traits tell tales of urban adaptation — van der Vegt, Wouter B. (2026) · DOI · View README in Vault

Zenodo publications

Data and code for "Predicting the functional impact of single nucleotide variants in Drosophila melanogaster with FlyCADD" — Beets, Julia et al. (2025) · DOI · View README on Zenodo