Knowledge Base

README Files for Research Data or Software

Every publication in PURR should include a README file provided by the author with the background information necessary for someone else to understand and use the dataset. A README file (preferably, a plain text document) provides information about the dataset such as a file manifest, a description of files, instructions for using the dataset or software, versioning information, changelog, and license information. A README file for complex datasets can also contain an outline of hierarchical structure and/or file dependencies.

Main components of a README file for a research dataset or software package include:

  • Introduction
    • Name of dataset or software package
    • Version
    • Release date
    • Contact information - Who and how to contact about the data or software
    • License, copyright, or instructions under which the dataset or software can be used
  • Description
    • The purpose of dataset or software package
    • The problem it solves or why it is useful
  • Data information
    • File manifest / types / formats
    • File date(s)
    • File version(s)
    • File functional purpose
    • File hierarchy and dependencies
    • Compilation / installation / configuration instructions
    • Known bugs / troubleshooting
    • System and hardware requirements needed to render / run data or software when appropriate
    • Changelog
    • How to submit bug notices
    • Location of additional documentation for the data or software package
  • Acknowledgments

When you publish your data, PURR generates a basic README file about the publication that includes the title, author, license, and a time stamp. It is up to the author to  ensure the publication includes a more detailed README file about the dataset itself, ideally covering the information listed above.


Additional Resources:

Simple README file documenting a dataset

Average README file documenting a dataset

Comprehensive README file documenting software


0 Dislike

Last updated

Comments on this entry

There are no comments on this entry.

Post a comment

Post a comment

Comments are closed on this entry.

Please keep comments relevant to this entry. Comments deemed offensive or inappropriate may be removed.

The Purdue University Research Repository (PURR) is a university core research facility provided by the Purdue University Libraries, the Office of the Executive Vice President for Research and Partnerships, and Information Technology at Purdue (ITaP).