Readme file

Overview

Questions

• How do I write a readme in such a way that my project is understandable for others?

Objectives

• Add a clear readme to your publication package
• The readme should make it clear when and where the research took place, where to find specific files, and how to interpret them

Infographic snippet: Provide a clear readme describing who was involved in the project, when the data was collected, which documents and files can be found where and how to interpret them

Steps to take

• According to the instructions in the Guideline for the archiving of academic research for Faculties of Behavioural and Social Sciences in the Netherlands (p.9) you should include a “readme file (metadata) describing which documents and files can be found where and how they should be interpreted”. A specific list of information that the readme file should contain is also provided:
  • Name of the person who stored the documents or files
  • Division of roles among authors, indicating at least who analysed the data
  • Date on which the manuscript was accepted, including reference
  • Date/period of data collection
  • Names of people who collected the data
  • If relevant: addresses of field locations where data were collected and contact persons (if any)
  • Whether or not an ethical assessment took place before the research, and, if relevant, study reference from and statements made by the Ethics Review Committee
  • Whether the data is made open or not and if not, a valid reason for not opening up the data
• Make sure you make the readme file in plain text, using a text editor, like Notepad/TextEdit/Vim, not Word (save as .txt). Alternatively, if you feel comfortable with Markdown, you can use the Markdown format (.md)

Example file

See the README.txt file from the EUR publication package example repository on Zenodo:

Figure: README file from the EUR publication package example

Other examples that you can use to get started with a readme:

• The Cornell guide to writing “readme” style metadata is a very helpful resource that includes a good readme template

• Colleagues from Leiden University provide a specific readme template based on the Guideline for archiving for Faculties of Behavioural and Social Sciences in the Netherlands

README exercise

Share your draft README with a colleague or with your neighbor during the workshop.

• Ask your peer to read through your README

• Can they answer the following questions based on the document:

  • Is it clear when and where the research took place?

  • Will they know where to find specific files when aiming to reproduce results?

  • Do they know what specific software to use?

  • Which improvements do they suggest to make the README as clear as possible?