Readme file

There are many different types of documentation that can be created to accompany research data, and their selection depends on the research context — for example, a README file.

A README is a file that helps others understand and use the shared data. It should clearly explain what is in the dataset.

The README file gives all the important information people need to understand and use the data correctly. It's a good idea to start writing it at the beginning of the research and keep it updated, so it's ready when the data is finished and shared.

It's a good idea to create a README file for each group of related files. If you have many similar files that belong together (like a set of MATLAB scripts), you can make one README for all of them. Sometimes, one file might need its own README. 

Write the README in plain English as a simple text file. Try not to use special formats like MS Word. Make it easy to read by using blank lines to separate important points. Use standard terms when possible, so others can understand it easily. 

Name the file "00_readme" to make it easy to find.  

Why should you add a README file to your dataset?

  • it helps others understand what the project and data are about, 
  • it tells people what software they need to open the files, especially if the files use special formats, 
  • it explains how the data is organized, so others can check and use it easily, 
  • a clear and complete README can make more people interested in your research and lead to new collaborations. 

What should it include?

  • dataset title, description, and research objective,
  • name and surname (ORCID)/institution/contact details,
  • information on the data collection methods and procedures,
  • timeframe of the study,
  • research tools used, 
  • data organization structure:
    - folder structure
    - file naming system (with examples)
    - relationships and dependencies between files
    - other relevant documentation files in the dataset (notes, supplementary files)
    - a short description and creation date for each major file
    - description of the file versioning system, if applicable,
  • software used to collect and process the data, including version numbers, 
  • file formats used in the dataset and recommended software,
  • applied quality control procedures,
  • dataset change log,
  • license under which the data is shared. 

Sample README file

Guides on how to prepare a good README file:

Guide to writing “readme” style metadata

Good data practices

A Beginners Guide to writing a Kickass README

FAIR-Cheatsheets