Describing research data with a README

A README is a text file that introduces and explains the contents of your research project folder or published data.

It usually describes the background, context, and collection of research data, and defines how the data may be reused by including a licence. It is usually written in a plain text format (.txt) so that anyone can open and read it.

A README file sits beside the data files and invites people to read it to make sense of the research project.

READMEs often come in handy when revisiting your own projects months or years after you’ve previously worked on them. For example, you may need to answer reviewer questions relating to your research data during the process of publishing a peer-reviewed journal article.

Recording information in a README as you collect and process your data means you will be able to remember what you did and why, and therefore respond to any integrity or verification requests.

When publishing or sharing data, it's helpful to provide a README file so that other people know what the data files contain, which parts of the research they relate to, how files relate to one another, how the data was generated, how data files have been processed or transformed, and whether or not there are any restrictions on who can view or access them.

1. Create a plain text file and name it README.txt.
   1. On Windows this can be done by right clicking the desktop, selecting ‘New’, ‘Plain Text Document’. Move the file into the project folder.
   2. On Mac, open the TextEdit application, create a new document, and select ‘Make Plain Text’ from the ‘Format’ menu. Save the file in the project folder.
2. Throughout your project, open the text file and add relevant research metadata and background information (see below). Save and close the file.
3. Include the README file alongside your data when you share or publish it.

There are no established rules for what to include in your README, but try to think about what you would want to know if you were interested in understanding and reusing the data. For example:

• Project information: Title, abstract, authors, ORCIDs, institutions, dates, funding, contact information
• Methods: how the data was collected or processed, software used (and versions)
• Files: File and folder list, how files relate to each other
• Tabular data: Key to variable names, acronyms, units for each column
• Terms for reuse: Licence, restrictions on use, recommended citation
• Related items: Links to related publications, data, websites, or other materials

• Cornell readme template. Cornell University provides a useful template which can be adapted to your own project.

Research Data Support Services
Email: researchdata@auckland.ac.nz

eResearch Engagement Specialist
Email: Tom Saunders