Making a useful README file for research projects

Summary: In my lab, every experiment have its own folder containing relevant files (stimuli, data, analysis). To make these actually useable, every folder should also have a README file with some basic information. Here I've provided an introduction to my thinking on README files for my lab.

As we set about organizing our shared network drive space, we agreed that every experiment should have its own folder (sensible), and that every folder should have a README file to make the files understandable. It quickly became apparent that my idea of a README file was not necessarily what everyone else had in mind—probably because I've spent more time downloading source code packages to install. Here I lay out what I think would be in a helpful README file, in the context of keeping track of experimental data in my lab—your experience and needs may vary!

What is a README file?

README files provide information about other files in a directory. Traditionally they are distributed with computer software: if you download many types of softare, you will get (among other files):

  • README (giving overview of the software)
  • INSTALL (installation instructions)
  • LICENSE (license)

(More on README files at Wikipedia.)

Here we are adapting the role of a README file to be more useful in the context of our lab.

Goals for README files in an our lab

The main goal for the README files in our lab is that so any lab member—now or in the future—can understand the basics of the experiment and what all of the other files in the folder are.

A side benefit is that by definition this will help people currently involved in the project understand what all of the files are, and encourage us to keep files better organized.

To achieve this, we want all of our README files to follow a certain pattern so that readers know what to expect, and to be as "futureproof" as possible.

General guidelines

  1. Name the file README. Not readme, read_me, ABOUT, etc. Knowing where to find the file is a great start.

  2. Write in plain text. Plain text files can be read by any operating system with no fancy software, including in the terminal (less README.txt). Better still, write in Markdown, which provides some guidlines for enhancing readability of text files using some simple conventions. In which case, maybe README.md.

  3. Include basic information about the project assuming you (the author) are not around to explain it. What is the title? Who were the main people involved? What was involved in the project?

We also sometimes create longer documents explaining the project in detail. These are great but can be separate from the README file, which should really be an overview pointing to other more detailed information.

Examples and further ramblings

Here's an example of a short README file written using Markdown (for a made up study):

Bagels vs. Donuts
=================

This experiment was run in Spring 2016.

Lead researcher: Jonathan Peelle
Other researchers: A. Priori, P. Osthoc

We compared the tastiness of bagels and donuts by showing participants a picture of a bagel or a donut and asking them to rate its tastiness on a scale of 1-5.


Files
-----

* The inputs folder contains the photo stimuli (in the stimuli directory) and Psychopy experiment (bagels.psyexp).
* The outputs folder contains data for each participant and a summary data sheeet (bageldonutdata.txt)
* The participant list is in bageldonut_participants.xls (password protected)


Last updated: 28 March 2016

This is obviously a silly example, but it contains all of the elements I've mentioned above: basic information about the study, who was involved, when it was run, and information about other files and folders that are important.

Other things you might want to include

  • The name of the larger grant or project
  • A link to a preregistration document, if applicable
  • Whether a paper resulted from the project
  • Any other resources (GitHub repositories, etc.) not in the main project folder

Now if you'll excuse me I'm going to go eat a donut.