What is a Readme File?

The README file provides information about the research data in order to help ensure that the data can be interpreted and reused correctly, both by yourself and by other people in the future.

 

Best practices (these lists are non-exhaustive)

There is not one right way to structure a good README file, but some best practices exist. For example:

 

When writing the README file:

  • If you plan to deposit the data in a repository, you will need to provide a README file. Creating this archive at the beginning of your research and constantly updating it will make this task easier for you.

 

Structure of the README file:

  • Name the file simply “README”.
  • Locate the README file at the root of the project.
  • If needed, create one README file per dataset / folder and use the same format for all.
  • Save it as a plain text file (txt) and avoide proprietary formats such as MS Word.
  • The information must be in English, in addition to the original language, to favour the reusability of the dataset.
  • Use standardized date formats: YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.
  • Follow the conventions used in archaeology for names, keywords and geospatial data. Whenever possible, use terms from standardized taxonomies and vocabularies.
  • Use of blank lines or dashes to separate the document into paragraphs.
  • Use bullet points or ordered lists instead of long paragraphs.

 

Content to include in the README file:

 

  • General information: Title, abstract, keywords, authors, ORCIDs, institutions, dates, funding, contact information and temporary and geographic data coverage.
  • Dataset persistent identifier.
  • Access information: licenses, terms of use and recommended citation.
  • Related items: links to related publications, datasets, websites or other research output.
  • Methodology: methods for processing and collecting data, software or information about instruments and standards.
  • File overview: files and folders structure description, file formats, files naming convention(s), original source if any, dataset version, updates.
  • Data dictionary for tabular data or databases with variables, units of measures, codes, symbols, abbreviations, etc.

Data documentation templates

README file template for archaeological datasets

This template is intended to support ICAC researchers in creating their README file. The document is organized by blocks and each block contains information between square brackets and their level of obligation. Download the template in TXT format (available in English, Catalan and Spanish).

README file template for master’s degree Final Project

This template is intended to support Master Students in creating their README file, which provides information about a data file and is intended to help ensure that the data can be correctly interpreted, by yourself at a later date or by others when sharing or publishing data.

Questions?

For more information and assistance, contact Documentation Centre and Library.

Contact

Sources:

CSUC [2021]. Readme template. Available: https://confluence.csuc.cat/pages/viewpage.action?pageId=104529933

Varrato, Francesco; Borel, Alain; Gabella, Chiara (2022). README file for datasets – Best practices and template. EPFL. Available: https://infoscience.epfl.ch/record/298249

Last updated: 19/01/2024