README files

README files are text (.txt) or Markdown (.md) files containing key contextual information about a project or dataset. This information is intended to ensure that the data can be correctly interpreted when it is used or reused.

It is customary to include the word README, in capital letters as the file name, followed by the extension in lowercase. Eg.: README.txt or README.md.

Characteristics

In principle, every data directory structure should contain at least one primary README file located at the root of the directory. Additional README files may also be included to accompany folders or files that require specific information.

A primary README file should contain at least the following information:

  • The names of the principal investigator and co-investigators of the study
  • A description of the methodology and tools used for data collection
  • The dates of data collection
  • A description of the directory hierarchy, the type of data it contains and the file naming convention
  • A complete list of all titles/codes/abbreviations and conventions used in the files
  • The conditions for sharing and access (licensing) during and after the end of the project

All of this information corresponds to the main types of metadata. For more information on this topic see the page: "Creating metadata".

How to create a README file?

README files can easily be created using a simple text editor (such as Noetpad++ for Windows) by adding a basic structure (headings, subheadings, etc.) but avoiding symbols and complex structures. The style should remain simple and accessible to a human audience.

McMaster University in Canada offers an online tool for creating a README file based on the very popular template from Cornell University.

mcmaster-readme-generator.png

As with all research data documentation actions, it is best to create READMEs or at least to document the information you will want to include in them at the beginning of the data collection, or even during the planning phase.

README example

4TU.ResearchData published an example of a README file they recieved in their data repository.

23 July 2026