Link Search Menu Expand Document
Research Data Management

What is README?

A README file provides information about a project 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. It contains information commonly required to understand the dataset, its contents, provenance, licensing and how to interact with it. A README file is generally named READMEand is typically a text or markdown file.

In short, a README is a portable, durable way to inform other researchers about how to navigate, collaborate, or extend your project.

Looking for a cheat sheet? Check out our one-pager

Looking for a template to reuse? Check out a very simple README template we prepared for you


Table of contents

Exercise 1

Please help us to make sense of a project.

Access this project:

Davis, Matthew, 2024, “Soil Adsorption Curves and Environmental Soil Data”, https://doi.org/10.5683/SP3/JGRIN0, Borealis, V1

Take a look at this project and try to answer the following:

  1. You got new data for ammonia absorption into soil from corktown, how would you go about generating the new model and plot?
  2. You want to recreate the whole project, what package(s) do you need to have installed to rerun everything?
  3. You have a question about this project, who and how can we reach the corresponding author?

How to Create a README

The Content

Every project is different, so consider which of the following applies to your project (a software project will have different sections than an academic research project).

  • Information - Name and contact information, how can people get in contact with you?
  • Description - Let users know what your project does. Provide context - this can be similar to an abstract for a research paper.
  • Installation - The project may work on your project but not everyone has all the installations and dependencies installed. Let people know what they need to install to make sure they can run the data smoothly.
  • Usage - Showing people an example of how your project/tool works can be very beneficial for users.
  • Contributing - Let other users/collaborators know how they can contribute to the project.
  • Acknowledgement - Use this area to acknowledge people/resources that contributed to the project.
  • License - If your project is open-source, mention the appropriate license.

The Process

You should create a README before having your project made public or sent out for collaboration. Even better, please consider making the README file first and continuously updating it.

You should place the README at the root directory of the project (check out our workshop on directory structures), this way, it can be one of the first files people will look at.

You can create a README with any text file format but Markdown is commonly used. Markdown allows you to add lightweight formatting and it is non-proprietary. Some other common formats you might see are plain text, R Markdown (common in R projects), and reStructuredText (common in Python projects). Using plain text helps preserve your information because it relies on durable, open standards rather than proprietary formats.

You can use any text editor, but some editors allow you to preview the Markdown while you are editing it.

Exercise 2

Template

We have created an example of a README for the project we looked at earlier. This sample file was designed to capture academic research projects. There are other templates available for other types of projects (software, data science, etc.). NOTE: The contents in the example template made up for educational purposes, do not reflect what the real study had in mind.

Now, let’s practice what we just learned.

Please download this README example . This template was designed to capture academic research projects and uses the project we looked at earlier for the content. There are other templates available for other types of projects (software, data science, etc.).

What are some things that you have noticed that may be specific to academic research? What are some things you would include if this were a software project?


Congrats!

You are now ready to write up a good README file so other researchers can understand your project with no problems!

Sources

Need help?

Please reach out to research.data@ubc.ca for assistance with any of your research data questions.