Documentation - README

Owned by Mandy Gooch
Last updated: 2024-49-15
3 min read

This article describes the types of information that should be included within a README file to assist secondary users in understanding the contents and structure of your research materials.

What is a README?

A README is a text document that can be used to capture information about your research project. It should describe your research project, the materials (data, code, etc.), and how your files are organized. Additional information such as methodology, data cleaning, data citations, access instructions, and licensing or terms of use may also be included within a README.

Essentially your README is a place to store descriptive information about your research throughout the life of your project. With everything in one location it is easy to get a snapshot of your project and its files. It’s also simple to pull these details into a record within a data repository – just copy and paste the information from your README straight into the repository record!

What Should be Included in a README?

In general, a README for data management should include the following information:

  1. Title of the project and contact information for all project team members.

  2. Full list of all relevant data files, their current versions and file naming convention, and their folder-file organization.

    1. You may also include information on who has access to which files for larger project teams.

    2. You might need to note if files are stored in separate locations (e.g., sensitive data is stored in a secure, encrypted location).

  3. Relationships between the files, as needed (e.g., run the scripts in a certain order, raw data vs. analysis data).

  4. Compute environment dependencies for analysis.

  5. Instructions for setting up and/or using software (if applicable).

  6. Complete data citations for any data obtained from another source.

  7. Access instructions for all original data sources, especially if there are any restrictions on sharing those original data within your chosen data repository.

    1. You should always verify that you are permitted to share these original source data or subsets of these data within a repository.

  8. Any additional information that may provide context to your research project and its materials such as sections on methodology, data cleaning processes, acknowledgements, etc.

A README should provide enough information for a user to understand the contents of your project folder(s). We recommend creating a README at the very start of your project to capture these pertinent details. It will save you a lot of time in the end.

What Format is Recommended for a README?

Since the README is a text document, we recommend sharing the final version as a .txt or .pdf for long term preservation and access.

Example READMEs

READMEs come in a variety of styles and there is no single standard layout. Here are a few good examples of READMEs from different disciplines to help you figure out which structure might work best for your project.

  1. Political Science Example: Slough, Tara; Fariss, Christopher, 2020, “Replication Data for: Misgovernance and Human Rights: The Case of Illegal Detention without Intent”, https://doi.org/10.7910/DVN/Q5PV4U, Harvard Dataverse, V1 README

  2. Github Software Example: Best-README-Template/BLANK_README.md at main · othneildrew/Best-README-Template

  3. Chemistry Example: http://dataabinitio.com/?p=378

  4. General Example: https://data.research.cornell.edu/data-management/sharing/readme/

 

CC-BY-NC

This work is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.

 

RDM Guidance formatting was influenced by The Writing Center, University of North Carolina at Chapel Hill Tips & Tools handouts.