Skip to main content
v2026.11,986 entries · CC-BY 4.0

What Is a README File? Purpose, Contents and How to Make One

A README file describes a folder for its reader. See the two kinds used in research, where GitHub displays a README, and how to make one.

Written and maintained by CASRAI Editorial Board

Published · Last updated

On this page

A README file is a plain descriptive file placed in a folder that tells a reader what is inside and how to use it. In a software project it is the first page a visitor sees; in a research dataset it is the document that lets someone else, or you in a year, interpret the files correctly. This guide covers both kinds, shows exactly where GitHub displays a README, and walks through making one.

What a README file is

A README file contains descriptive information about the content of the directory in which it sits. The convention dates to the mid-1970s, and the name is capitalised so that it stands out at the top of an alphabetical file listing. There is no formal standard for it: common names are README, README.txt (plain text) and README.md (Markdown). Commonly seen contents are setup instructions, usage, a file manifest, the licence, contacts, known bugs, troubleshooting, credits and a changelog.

Two kinds matter in research, and they have different jobs:

  • Project (code) README. Explains what a software project does, why it is useful, how to get started, where to get help, and who maintains it.
  • Data README. Describes a dataset so that it can be correctly interpreted by you at a later date or by others: who collected it, when, what each file holds, and what the variables mean.

What a README is used for in research

In research a README is the lowest-cost piece of documentation that travels with the files. Cornell’s Research Data Management service describes a data README as a document intended to help ensure that the data can be correctly interpreted. It helps whether the reader is you at a later date or somebody else. For the wider sharing picture, see the FAIR dataset checklist.

Use a project README when you share code, and a data README when you share data. When you share both, keep a README for each so that the reader finds the right description next to the right files. For a ready-made structure, see our README template for research data and code, which this page deliberately does not repeat.

Where GitHub shows a README

GitHub displays a README automatically on the front page of the repository it belongs to. According to GitHub Docs, the following rules apply:

  • A README is shown if it sits in the hidden .github directory, the repository root, or the docs directory. If several exist, GitHub chooses in that order: .github first, then the root, then docs.
  • Content beyond 500 KiB is truncated.
  • Relative links are recommended. A link starting with / is relative to the repository root, whereas absolute links may not work in clones of the repository.
  • GitHub generates a table of contents from the headings of a rendered Markdown README, available from the Outline menu icon.

GitHub’s own guidance is that a README should contain only the information developers need to get started using and contributing to the project; longer documentation belongs in a wiki. If you are new to the platform, GitHub tutorials for beginners covers repositories and commits.

How to make a README file

There are two routes: create it together with a new GitHub repository, or write a file by hand in any folder.

Create a README with a new GitHub repository

  1. In the upper-right corner of any GitHub page, choose to create a new repository.
  2. Type a short, memorable name for the repository.
  3. Optionally, add a description.
  4. Choose the repository visibility.
  5. Toggle Add README to On.
  6. Click Create repository.

The contents of the README are then shown automatically on the front page of the repository. Edit the file to add your own content.

Write a README by hand for a dataset or folder

  1. Create a new text file in the folder and name it so that it is easily associated with the data file or files it describes. One README can describe a cluster of files or a single file.
  2. Save it as a plain text file rather than a proprietary format such as Microsoft Word.
  3. Fill in the sections below, leaving blank lines between key items.
  4. Reuse the same order and terminology across all your READMEs.
  5. Write dates in ISO 8601 format (YYYY-MM-DD).

What to put in a README

Project README checklist

GitHub Docs lists what a README typically covers:

  • what the project does
  • why the project is useful
  • how users can get started
  • where users can get help
  • who maintains and contributes to the project

Data README checklist

Cornell groups data README content into five parts: general information, data and file overview, sharing and access, methodology, and data-specific details. At a minimum it recommends:

  • a title and contact details
  • collection dates and location
  • a description of each file
  • licences or restrictions
  • methods
  • software used, with versions
  • variable names, units and missing-data codes

For naming the files you describe, see file naming and folder structure conventions for research data. A README describes the data in prose, while formal metadata records do the same in a structured, machine-readable way. For software citation details, see CITATION.cff.

How to read a README

Start at the top, where the title and a one-paragraph description should tell you whether the project or data is what you need. Next, look for the getting-started or file-overview section, then the licence and the contact. In a data README, check the variable names, units and missing-data codes before opening any data file, so you interpret the values correctly.

Troubleshooting

My README does not appear on GitHub

Check the location. GitHub shows a README from the .github directory, the repository root or the docs directory, and if more than one exists it picks .github first, then the root, then docs.

My README is cut off

GitHub truncates content beyond 500 KiB. Move long documentation to a wiki or separate pages and keep the README to what is needed to get started.

Use relative links. A link beginning with / is relative to the repository root, while absolute links may not work in clones.

Plain text vs Markdown

Format File name Notes
Plain text README or README.txt Recommended for data READMEs by Cornell, because a plain text file avoids proprietary formats such as Word.
Markdown README.md Rendered by GitHub, which also builds a table of contents from the headings.
Word processor README.docx Cornell advises against proprietary formats for a README.

FAQ

How to make a README file?

On GitHub, create a new repository and toggle Add README to On before you click Create repository; the file is then shown on the repository front page. For a dataset, create a plain text file next to the data, name it so it is clearly associated with the files it describes, and cover the title, contact, dates, file descriptions, licence, methods, software versions and variable details. The numbered steps above give both routes.

What is a README file used for?

It describes the content of a folder: for a software project, what the project does and how to start using it; for a dataset, how to interpret the data correctly.

Should a README be .txt or .md?

Both are in common use and neither is a formal standard. Use README.md on GitHub for rendered headings, and plain text for data you deposit or share, as Cornell recommends.

Sources

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about What Is a README File? Purpose, Contents and How to Make One

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →