README template
Use this template to prepare the main documentation file for a research dataset. A completed README helps other users understand what the dataset contains, how its files are organised, how the data were produced and processed, and how they can be accessed, interpreted and reused.
Resource information
Resource type
Documentation template
Intended users
Researchers, research groups, data curators and data stewards
Recommended use
Dataset publication, FAIR data packaging and repository deposit
Status
Recommended template of the Competence Center
Download the README template
Select the format that is most convenient for your workflow. Markdown is recommended for computational datasets, code and machine-readable documentation. DOCX may be used for preparation and institutional review.
What is a README?
A README is the primary documentation file supplied with a research dataset. It explains what the dataset contains, how its files and folders are organised, how the data were collected or created, which processing steps were applied, and how the files can be opened, interpreted and reused.
The README complements the metadata entered in a repository. It provides file-level, methodological and practical information that may not fit into the repository metadata fields.
README and repository metadata are complementary
Repository metadata help users find and identify a dataset. The README helps them understand and use its files correctly.
What the template covers
The template contains fourteen sections organised into four practical documentation areas.
Dataset identification and context
Dataset title, version, authors, institutions, responsible contact, research group, funding, scientific domain, purpose and related publications.
Files, structure and methods
Dataset size, file formats, folder structure, description of the main files, data collection or creation methods, equipment, software and computational environment.
Opening, interpretation and reuse
Instructions for opening and using the files, software dependencies, processing and analysis steps, known limitations, access conditions, licence and recommended citation.
Versions, rights and support
Personal or sensitive data, third-party materials, version history, changes, responsible contact and additional notes.
How to use the template
1. Download
Download the Markdown or DOCX version.
2. Complete
Replace the guidance text with information about your dataset.
3. Adapt
Keep the relevant sections and mark those that do not apply.
4. Check
Check consistency with metadata, files and access conditions.
5. Include
Place the completed README in the root directory of the dataset.
Recommended file name and location
Use a clear and conventional file name:
- README.md — recommended for most FAIR data packages;
- README.txt — suitable for plain-text documentation;
- README.pdf — may be included as an additional fixed-layout version;
- README.docx — suitable as a working version but less convenient as the only preservation format.
Приклад структури пакета
dataset-name/ │ ├── README.md ├── manifest.csv ├── metadata.json │ ├── data/ ├── scripts/ ├── documentation/ └── results/
Minimum information to include
At minimum, the README should identify the dataset and its authors, explain what the data contain, describe the main files and their formats, state how the data were produced, provide instructions for opening and interpreting the files, and specify access, licence and contact information.
- Dataset title and version
- Authors and contact
- Short dataset description
- File and folder structure
- Description of the main files
- Data collection or creation method
- Software and file-opening instructions
- Access conditions and licence
- Related publication or project
- Version history
Important notes
- Do not include passwords, access credentials or confidential personal information in the README.
- Do not describe restricted or sensitive information in more detail than is permitted by the applicable access policy.
- Use the same dataset title, author names, identifiers, version and licence in the README and repository metadata.
- Clearly distinguish raw data, processed data, scripts, documentation and derived results.
- Specify software versions, dependencies and configuration files when they are required to interpret or reproduce the data.
- Update the README when the dataset structure, version, access conditions or content changes.