README files explained
A README file can be as complex or as simple as you want it to be. Its core purpose is to make sure people who use your data understand it and use it appropriately. It also backs up the robustness of your methodology by allowing space for you to fully explain how the data was generated.
The outline below shows one way of approaching a README file, questions you could answer, and information you could include.
Data and file overview
- For each file, a short description of what it contains, and who created it
- format of the file if not obvious from the file name
- if the data set includes multiple files that relate to one another, the relationship between the files or a description of the file structure that holds them - you could use terminology like 'dataset' or 'study' or 'data package'
- Dates the files were updated (versioned) and the nature of the updates
- Description of methods for data collection or generation - include links or references to publications or other documentation containing experimental design or protocols used
- Description of methods used for data processing - describe how the data was generated from the raw or collected data
- any instrument-specific information needed to understand or interpret the data
- standards and calibration information, if appropriate
- describe any quality-assurance procedures performed on the data
- definitions of codes or symbols used to note or characterize low quality/questionable/outliers that people should be aware of
- Count of number of variables, and number of cases or rows
- List of variables, including full names and definitions of column headings for tabular data - spell out any abbreviated words
- Units of measurement
- Definitions for codes or symbols used to record missing data
- Specialized formats or other abbreviations used