README Template for Research Code and Data

Q: Where does the README go in a repository?

GitHub checks .github , then the root, then docs , and shows the first match.

A README template for research has to answer a different question depending on what you are sharing. A README for a dataset describes files, variables and how the data were collected. A README for analysis code describes what software to install, what hardware it needs, and which script to run first. The two best-known free templates split along exactly that line: Cornell’s data-management README guide for data, and the Social Science Data Editors’ template README for code and replication packages. This page tells you which one to start from, gives a copy-ready outline that combines both, and lists where GitHub will and will not display the file. Sources were checked on 2026-10-29.

Which README template do you need: data or code?

Use a data README when the thing you are depositing is data, and a code or replication README when the thing you are depositing is a set of scripts that reproduce results. Many projects need both, and the safest approach is one project-level README that points to a per-file or per-folder description.

Data README. Cornell Research Data Management’s guide to README-style metadata lays out five sections: general information, data and file overview, sharing and access information, methodological information, and data-specific information.
Code or replication README. The Social Science Data Editors (SSDE) template README, which carries the DOI 10.5281/zenodo.7293838, has three components: a Data and Code Availability Statement, Computational Requirements, and Instructions for Data Preparation and Analysis.
Software project README. A README for a software tool (rather than a replication package) has its own conventions. Cornell’s eCommons also hosts a “Readme Template for Software” by Dianne Dietrich and Lencia McKee, issued in 2025 under a CC0 1.0 licence, for that case.

If you are preparing a replication package, the SSDE structure is the one to start from. For an example of a journal policy that requires a README with deposited code and data, see our guide to the AEA data and code availability policy.

Template for a data README

Cornell’s five sections, in order, with what each one asks for:

1. General information

Dataset title; name, institution and email for the principal investigator, any co-investigators and the contact person; dates of data collection; geographic location of collection. Keywords, language and funding information are recommended additions.

2. Data and file overview

A description of each file, the date each file was created, the relationships between files, and the dates of any version updates.

3. Sharing and access information

Licences or restrictions on the data. A recommended citation for the data and links to related publications are listed as recommended rather than required.

4. Methodological information

How the data were collected or generated (with links to protocols), how they were processed, and the versions of any software and instruments used. Quality-assurance and calibration information is recommended.

5. Data-specific information

Repeated for each data file: the number of variables and cases, a list of variables with full names and definitions, units of measurement, and the codes used for missing data.

Copy-ready skeleton (plain text, as Cornell recommends):

README for [dataset title]

1. GENERAL INFORMATION
   Title:
   Principal investigator (name, institution, email):
   Co-investigators:
   Contact person:
   Date(s) of data collection (YYYY-MM-DD):
   Geographic location:
   Keywords / language / funding (recommended):

2. DATA AND FILE OVERVIEW
   File list with a one-line description of each file:
   File creation dates (YYYY-MM-DD):
   Relationships between files:
   Version update dates (YYYY-MM-DD):

3. SHARING AND ACCESS INFORMATION
   Licence or restrictions:
   Recommended citation (recommended):
   Related publications (recommended):

4. METHODOLOGICAL INFORMATION
   Collection or generation methods (link to protocols):
   Processing steps:
   Software and instrument versions:
   Quality assurance / calibration (recommended):

5. DATA-SPECIFIC INFORMATION (repeat for each file)
   Number of variables / number of cases:
   Variable list (full name and definition):
   Units of measurement:
   Missing-data codes:

Template for a code or replication README

The SSDE template is built around three components. The template page shows the latest release candidate, so cite the DOI.

Data and Code Availability Statement

The SSDE template says a good README should first provide a brief overview of the available material. Put this at the top, before any installation detail.

Computational Requirements

List the software and versions, any additional packages, and the hardware used: operating system, CPU, memory and disk, plus the wall-clock run time of the full analysis. These are the details a reader needs to judge whether they can rerun the package on their own machine.

Instructions for Data Preparation and Analysis

Give separate instructions for each stage. According to the template, a good package uses a minimal number of automated scripts, so that the reader’s path from raw data to results is short and clear.

Copy-ready skeleton:

README for [project title]

DATA AND CODE AVAILABILITY STATEMENT
   Brief overview of the material provided:
   Where the data come from and how they can be accessed:

COMPUTATIONAL REQUIREMENTS
   Software and versions:
   Additional packages:
   Hardware (OS, CPU, memory, disk):
   Approximate wall-clock run time:

INSTRUCTIONS FOR DATA PREPARATION AND ANALYSIS
   Step 1 - data preparation: [script name, what it reads, what it writes]
   Step 2 - analysis: [script name, what it reads, what it writes]
   Step 3 - tables and figures: [script name, which outputs it produces]

The software and package versions you record here are the same information a reproducibility workflow captures automatically; the README is the human-readable summary of it. If your code is meant to be cited as software in its own right, a CITATION.cff file gives citation tools the metadata in a machine-readable form, and our guide on FAIR software shows how software expectations differ from those for data.

Format, naming and placement

Plain text or Markdown?

Cornell’s data-management guide says to write the README as a plain text file and to avoid proprietary formats such as Microsoft Word where possible. The SSDE template is distributed in several formats (HTML, LaTeX, Word, PDF and Markdown), with HTML recommended for reading. The Cornell eCommons software template downloads as Markdown (.md) and plain text (.txt). In practice: use plain text for a data deposit, and Markdown where the file will be rendered on GitHub.

Dates and naming

Cornell recommends ISO 8601 dates (YYYY-MM-DD), naming the README so that it is easily associated with the data file or files it describes, and formatting multiple README files identically. One README can cover a cluster of files or a single file. For naming and folder conventions around the README, see our guide to file naming and folder structure for research data.

Where GitHub shows it

GitHub’s documentation says a README typically explains what the project does, why it is useful, how to get started, where to get help, and who maintains and contributes to it. GitHub looks for the file in the .github folder first, then the repository root, then docs, and displays the first one it finds. Content beyond 500 KiB is truncated. Relative links are recommended because absolute links may not work in clones, and GitHub generates a table of contents from your headings through the Outline menu.

Free README templates compared

Template	Best for	Structure	Formats / licence
Social Science Data Editors, Template README	Replication packages (code and data)	Data and Code Availability Statement; Computational Requirements; Instructions for Data Preparation and Analysis	HTML, LaTeX, Word, PDF, Markdown; CC-BY-NC
Cornell Research Data Management, README-style metadata guide	Datasets	General information; data and file overview; sharing and access; methodological information; data-specific information	Guidance page; recommends plain text
Cornell eCommons, Readme Template for Software	Research software	See the template itself	Markdown and plain text; CC0 1.0 (version 3, 2025-10-22)
GitHub Docs, About READMEs	Any repository shown on GitHub	What the project does, why it is useful, getting started, help, maintainers	Guidance page, not a downloadable template

Common README mistakes

Putting setup before the overview. The SSDE template asks for a brief overview of the available material first.
Leaving out hardware and run time. The SSDE Computational Requirements component lists operating system, CPU, memory, disk and wall-clock time.
Using a proprietary format. Cornell advises plain text over formats such as Word.
Formatting multiple READMEs differently. Cornell says to format them identically.
Ambiguous dates. Use YYYY-MM-DD.
Absolute links in a repository README. GitHub notes they may not work in clones.
A huge README on GitHub. Anything past 500 KiB is truncated.

FAQ

What should a README for a research project include?

For data: general information, a file overview, sharing and access terms, methods, and data-specific details such as variables, units and missing-data codes. For code: an availability statement, computational requirements, and stage-by-stage instructions. The skeletons above combine the two.

Should a research README be Markdown or plain text?

Cornell’s data guidance recommends plain text over proprietary formats. If the file lives in a GitHub repository, Markdown is rendered there; the Cornell eCommons software template is available in both Markdown and plain text.

Where does the README go in a repository?

GitHub checks .github, then the root, then docs, and shows the first match.

Is there a README template for software?

Yes. Cornell eCommons publishes a “Readme Template for Software” (CC0 1.0) as Markdown and plain text. For a reproducibility package, the SSDE template is the one aimed at that purpose.

Sources

Social Science Data Editors, Template README, social-science-data-editors.github.io/template_README (DOI 10.5281/zenodo.7293838), checked 2026-10-29.
Cornell Research Data Management, Guide to writing “readme” style metadata, data.research.cornell.edu/data-management/sharing/readme, checked 2026-10-29.
Cornell eCommons, Readme Template for Software (Dianne Dietrich, Lencia McKee), ecommons.cornell.edu, checked 2026-10-29.
GitHub Docs, About READMEs, docs.github.com, checked 2026-10-29.