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
.githubdirectory, the repository root, or thedocsdirectory. If several exist, GitHub chooses in that order:.githubfirst, then the root, thendocs. - 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
- In the upper-right corner of any GitHub page, choose to create a new repository.
- Type a short, memorable name for the repository.
- Optionally, add a description.
- Choose the repository visibility.
- Toggle Add README to On.
- 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
- 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.
- Save it as a plain text file rather than a proprietary format such as Microsoft Word.
- Fill in the sections below, leaving blank lines between key items.
- Reuse the same order and terminology across all your READMEs.
- 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.
Links in my README break after cloning
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
- GitHub Docs, About READMEs (checked 2026-10-29).
- GitHub Docs, Quickstart for repositories (checked 2026-10-29).
- Cornell Research Data Management, Guide to writing “readme” style metadata (checked 2026-10-29).
- Wikipedia, README, for history and naming conventions (checked 2026-10-29).







