READMEs for Documenting Data and Workflow

Overview

Teaching: 20 min
Exercises: 20 min

Questions

• What are best practices for documenting the phases and workflows of a research project?

Objectives

• Understand the importance of READMEs as a way to document the steps of a research project

• Create a README for a research projects

• Set up the folder structure (including filename) for a project

• Document the decision-making and the research process

Challenge: Reviewing a README

Review this README and identify what you think are the key details to include in a README when describing a research project. Think about why they might be important details.

Solution

This README lists the researchers who received funding, basic funding information, basic descriptions of files in the dataset. This README is an example of how a README can be used to give a basic description of a research project. 

Documentation with READMEs

READMEs are commonly used to document software installation, and can also be used for:

• Research project workflows
• Describing datasets

READMEs are typically a .txt or .md (markdown) file format

• These file formats can be opened universally

What to Include in a README?

• Title of research project and/or dataset
• Names, contact information, and institutional affiliation for those associated with the project
• Funding sources or institutional support
• A list of files and folders, a description of their contents, how to use them
• For each file name, a short list of the data that it contains
• The date that the file was created

Key Points

• READMEs are an important and simple tool for documenting various aspects of a research project, including assets (data) and workflow