What is a README?

A README file is an important document that accompanies your dataset. It provides key information about your project to make sure the dataset(s) can be correctly understood, reanalyzed, and reused by you and others. Without a README file, you could spend hours combing through related manuscripts or searching online to decipher file contents, analysis procedures, and acronyms.

It’s good practice to have this document when conducting your research because it helps maximize the usability of your data in the long-term. You may also notice that many data repositories, including UBC’s, will ask you to include a README file as part of your data deposit.

However, keep in mind that a README file complements your dataset. It does not replace the metadata that data repositories (e.g. Borealis or FRDR) ask you to provide when you deposit your data. The repository’s metadata will support findability, accessibility, interoperability, and reusability within and between data repositories, while the README is portable and continues to describe the dataset, even after it has been separated from its original context.

Table of contents

Warm-Up: Exercise 1

Let’s start by looking at a dataset deposited in Borealis. Please navigate to this dataset by clicking on the hyperlinked DOI and then scroll to view the deposited content under the “Files” tab.

Here is the dataset:

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

Once you’ve looked through the files included in the dataset, try to answer these questions:

  1. If you received new soil data from Corktown, how would you create a new model and plot?
  2. If you wanted to replicate this project, what software package(s) would be required to run the exact data analyses?
  3. If you had questions about this project, who could we contact and how?

The main takeaway here is that data without information about it (contained in a README file) is not useful to us!

Creation considerations for a README file

Create your README file at the start of your project, or at least before your project is shared and becomes publicly accessible. Typically, making one README file is enough for a dataset or a set of files with similar content. However, if multiple READMEs are needed, then you should format them the same way to maintain consistency.

  • As soon as possible, update your README file to reflect any changes made to your research project so you don’t lose any important information

Any text editor can be used to create a README file. Commonly used formats are Markdown and TXT because of their lightweight formatting. These plain text formats also don’t rely on proprietary software, which means that they are more durable in the long-run, help with preserving your information better, and can be opened by various applications. R Markdown (common in R projects) and reStructuredText (common in Python projects) are also other common formats of README files.

Once your README file is created, store it in the root directory of your project folder (here is our workshop on directory structures), so that it will be the first file seen and easily accessible.

Stylistic considerations for a README file

How your README is written is also important. Consider some of these best practices for data documentation:

  • Be as clear and specific as possible when describing elements of your project
  • Follow a style that’s consistent and agreed upon by the research team
  • Use descriptive titles, including your README file itself along with other subsections within your README file
  • Add in relevant dates, such as when the README file, dataset(s), and other files were created and updated. These dates should follow a standardized format, like ISO 8601 (YYYY-MM-DD or YYYYMMDD) to maintain consistency
  • Consider your audience: will you be using jargon? If so, perhaps you may want to clarify the specialized terminology or look for an alternative word. If you refer to acronyms or abbreviations, make sure you’re defining them
  • You could also enhance research transparency by addressing any research limitations (such as missing data), file quantities, and file versions
  • The README file can simply be named README or _README, but additional information can be added if necessary

Minimum README file requirements

Although every research project is different, a README file should at least include the 9 elements outlined in the table below, which will help users understand the basic details of your dataset(s) and evaluate the level of relevance to them.

These minimum requirements mirror the report by the Digital Research Alliance of Canada’s Borealis Expert Group: README Elements for Research Data Deposits in Borealis, along with additional elements to consider for possible README file enhancement. These elements also align with the Tri-Agency’s language from an FAQ on data retention, deposit, and availability (see question #17).

README metadata element Definition
Author/creator The person(s), corporate body(ies), or agency(ies) responsible for creating the dataset. List authors in the order they should appear in citations. Where possible, include ORCIDs to uniquely identify researchers and support proper attribution.
Title The full, descriptive title by which the dataset is known. The title should clearly convey the subject matter and scope of the data so a reader can assess its relevance without opening any files.
Description/summary A narrative summary of the dataset’s purpose, content, and scope. Describe why the data were collected, what is captured, how the data are structured, and what they might be used for. Write for a broad academic audience so that researchers unfamiliar with the project can determine whether the data suit their needs.
Contact information The name, institutional affiliation, and email address of the person(s) responsible for answering questions about the dataset. If the primary contact may change over time, consider also providing an institutional or project-level address so users can always reach someone knowledgeable about the data.
License information The legal terms under which the dataset may be used, shared, and redistributed. Provide the full license name and version (e.g., Creative Commons Attribution 4.0 International, CC BY 4.0). If a standard open license does not apply, describe any restrictions on use, sharing, or derivative works.
DOI/persistent identifier A Digital Object Identifier (DOI) or other persistent identifier assigned to the dataset, ensuring it can be reliably located and cited over time. If a DOI is not yet assigned at deposit, note it as pending and update the README once available.
Research methodology A summary of the research methods used to generate the dataset, covering study design (e.g., experimental, observational, survey-based, or computational), data collection instruments or procedures, and key processing steps applied to the raw data. The goal is to provide users with sufficient context to assess the data’s reliability and understand what would be required to replicate the data.
Related publications Journal articles, reports, or other scholarly works that are directly based on or make use of this dataset. Provide full citations with DOIs where available. This helps users understand how the data have been analyzed, identifies methodological context, and ensures the researchers who generated the data receive appropriate credit and citations.
Software/tools used The names and versions of any software, programming languages, or specialized tools needed to open, read, or reproduce the dataset or its analyses (e.g., R 4.3.1, Python 3.11, MATLAB R2023b). Include the operating system where relevant. This information is essential to reproducibility and helps users determine whether they can work with the data using the tools available to them.

Exercise 2

Let’s revisit the dataset cited in the warm-up exercise. Recall how difficult it was to understand the dataset, so we created an unofficial README for it to help understand the dataset better.

Please navigate to the sample README provided below, open the file, view the content, and answer the following questions:

  1. What existing elements or pieces of information are useful?
  2. What elements or pieces of information are underdeveloped or missing?
  3. If you wanted to enhance this README file, what would you add?

Sample README file

Here is the sample README file you can view and download for exercise 2. It includes the 9 minimum elements to capture academic research projects.

As a reminder, in the note box at the top, you can also download a README template that can be filled in and modified to fit your project! Both the sample and template README files are in plain text format and can be opened in many applications.

Please note that the content of the sample README file was fabricated for educational purposes and does not reflect the real project’s objectives.


Here is a breakdown of what we covered: READMEs are important documents containing information about your project’s data. They help ensure your data is correctly interpreted and navigated for you and others in the future when revisited. READMEs should be created at the start of your project and maintained throughout, and include content that is appropriate to your project. Lastly, it’s best to write your README in a non-proprietary format, like TXT or Markdown.

Congrats!

Hooray! You are now ready to write up a good README file so you and 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.

View in GitHub

Loading last updated date...