If you share a dataset with nothing else, the next person has to guess. Which file is the raw version? Is "inc" income or incident? Why do 212 rows have a blank in the third column? Those guesses end up in someone's analysis, and sometimes in their published paper. A README is a short text file that answers the questions before they're asked, and it's the cheapest thing you can add to make shared data usable.
This guide covers what to put in a dataset README, gives you a template to copy, and lists the habits that make a README useful instead of ornamental. It fits any field and any size of dataset. It also pairs with the codebook, which handles variable-level detail, and with the data availability statement you'll write for the paper.
What a README is for
A README has one reader in mind: someone who doesn't know you, doesn't know your project, and is opening the folder cold. That might be a graduate student next year, a reviewer, a journalist, or you in 2031. They can't ask you what a file means, so the file has to say.
It does a second job too. Writing it forces you to notice what you never documented. If you can't say how a column was computed, or which survey wave a file came from, it's better to find that out now than after the deposit. A repository like the ones in the repository guide will often ask for a README or an equivalent description, and some curators will send a deposit back without one.
What to put in it
You don't need all of these for every dataset. Start with the first six and add the rest where they apply.
- Title and a one-paragraph summary. What the data are, what they were collected for, and the time period and place they cover. Write it so a stranger can decide in thirty seconds whether the dataset is useful.
- Who made it. Names, affiliations, and a contact email that will still work. If you can, include an ORCID for each author. Say how you'd like the data cited, and link to the dataset citation or paste the exact string.
- The files. A list of every file and folder with one line each: what it contains, its format, and its relationship to the others (raw, cleaned, analysis-ready). If your naming convention carries meaning, such as a date or participant code in the filename, explain it here. The organization guide shows a layout that makes this list short.
- How the data were collected or generated. Instrument, survey, sensor, simulation, or source system; sampling or selection; dates; software and version numbers. Link the protocol or paper if one exists.
- How the data were processed. What you changed between raw and final: cleaning rules, recodes, exclusions, merges, imputation, de-identification. If code does this, name the scripts and the order to run them. This is the section that makes the dataset reproducible.
- Variables and units. Either a table in the README or a pointer to the codebook. Include units, the codes for missing values (blank, NA, -99), and any variable that was derived rather than collected.
- Known problems. Gaps in coverage, a sensor that failed for a week, a question that was changed midway, a subgroup too small to analyze. A short honest list builds more trust than silence does, and it saves reusers from rediscovering the problem.
- Terms of use. The license or the access conditions, in a sentence. If the data came from a data use agreement, say that redistribution is restricted and who to ask. If participants consented under specific limits, the consent language sets what you can say here.
- Privacy and sensitivity. What was removed or masked, and what a reuser must not attempt (linking to other sources, re-identifying people). See the de-identification guide.
- Related materials. The paper, the code repository, the preregistration, the funder and award number, and earlier versions of the dataset.
- Version and date. A version number, the date of this release, and a short change note. If you fix an error after publication, the README is where you say so.
A template you can copy
Paste this into a plain text file called README.txt, and fill in or delete each line. The bracketed parts are yours to complete.
TITLE: [Dataset title]
VERSION: [1.0] RELEASE DATE: [YYYY-MM-DD]
SUMMARY
[Two to four sentences: what the data are, why they were
collected, time period, place, number of records.]
CREATORS
[Name, affiliation, ORCID, email] (contact for questions)
Suggested citation: [Author. Year. Title. Repository. DOI]
FUNDING AND RELATED WORK
[Funder, award number]. Paper: [DOI]. Code: [URL].
FILES
data/raw/survey_wave1_raw.csv Raw export, one row per respondent
data/clean/survey_wave1_clean.csv Cleaned file used in the paper
docs/codebook.csv One row per variable
code/01_clean.R Raw to clean (run first)
code/02_models.R Tables 2 and 3
METHODS
Collection: [instrument, dates, sampling, mode]
Processing: [exclusions, recodes, merges, software and versions]
VARIABLES
See docs/codebook.csv. Missing values are coded [NA / -99].
Derived variables: [name: how it was computed]
KNOWN PROBLEMS
[Gaps, changes in wording, small groups, anything a reuser
would want to know before trusting a result.]
TERMS OF USE
License or access conditions: [CC BY 4.0 / restricted, contact ...]
Do not attempt to identify participants or link to other data.The file names in the FILES block are examples. Use your own, and keep the list in the same order a person would browse the folder.
Habits that make it work
Write it as you go. The README is easiest to write when the details are fresh, and nearly impossible to reconstruct from memory a year later. Start the file on the first day of data collection and add a line whenever you make a decision you'd have to explain.
Keep the format boring. Plain text, UTF-8, short lines. Don't paste in screenshots of tables, and don't depend on colors or fonts. A README should read the same in a repository preview, a terminal, and a text editor.
Say what a column means, not what it's called. "status: 1 = enrolled at census date, 2 = withdrew before census date, 3 = never enrolled" is useful. "status: the student's status" isn't. This is where the codebook earns its keep.
Give every folder its own README only when it needs one. One README at the top covers most projects. If a subfolder is a self-contained dataset that might be deposited or shared on its own, give it a short README of its own, so it still makes sense when it travels alone.
Have someone else read it. Ask a colleague or a student who wasn't on the project to find one variable and explain where it came from, using only your files. Wherever they get stuck is where the README is thin.
Update it when the data change. A README that describes version 1 of a dataset that's now on version 3 is worse than none. Change the version line and the change note every time the files change.
Common mistakes
- Writing for yourself. Abbreviations, project nicknames, and "the usual cleaning" mean nothing to a stranger. Spell them out once.
- Describing the paper instead of the data. A reuser doesn't need your argument. They need to know what's in the files.
- Leaving out the processing steps. Saying the data are "cleaned" without saying how invites suspicion and blocks any attempt to replicate.
- Listing no contact, or a contact that expires. A student email that bounces after graduation ends the conversation. Use a durable address, a group inbox, or the library's data services contact.
- Skipping the license. Without terms, reusers can't be sure what they're allowed to do, and many will simply not use the data.
- Hiding the problems. Every dataset has some. The README is the right place to say so.
README, metadata, and codebook: who does what
These three get mixed up, and it's worth a minute to separate them. Metadata is the structured record a repository stores and indexes: title, creators, keywords, license, DOI. It's what makes the dataset findable. The codebook documents variables. The README ties them together for a human reader and carries everything the other two have no room for. You'll usually write the metadata once at deposit, the codebook as the data take shape, and the README throughout.
For a longer worked example of README-style documentation, the data services team at Cornell University publishes a guide to writing README-style metadata with its own template. Your institution's library may have one too. [Placeholder: add the name of your own library's or research office's README template, if there is one, so this guide points to local help.]
If you support researchers
A README template is one of the easiest things a library or research office can hand out, and one of the most used. A single page with the template above, adjusted to your field and your repository, answers a question researchers ask every cycle. It makes a good companion to DMP review, since the plan promises documentation and the README is where it gets delivered. If you're starting research data services, it's a quick first handout. I help campuses build these as part of a data services engagement, and the DMP checklist is a good place to link it from.
Common questions
What is a README file for a dataset? A plain-text file that sits next to the data and tells a stranger what the files are, how they were made, what each column or variable means, who can use them, and who to contact. It's the first thing a reuser opens.
Should a README be Markdown or plain text? Either works. Plain text (README.txt) opens everywhere and will still open in twenty years. Markdown (README.md) is fine if you keep the formatting light. Avoid Word and PDF, which are harder to read in a terminal or a repository preview.
Is a README the same as a codebook? No. The README describes the dataset as a whole: its origin, files, methods, and terms. The codebook describes each variable. For a small dataset you can put both in one file, but for anything with more than a few dozen variables, keep the codebook separate and point to it from the README.
Do repositories still want a README if I fill in their metadata form? Usually yes. The form feeds search and the citation record, but it rarely has room for file-by-file notes, processing steps, or known problems. A README carries those, and it travels with the files if the dataset is ever downloaded or moved.