Write a dataset README that explains how the files fit together
Orient readers to a dataset package with a checked file map, record units and links to detailed documentation.
About 4 min read · Allow extra time for the practical checks
Tell a new reader what the dataset contains, which files to open first and how those files relate. A folder of accurately named files can still be difficult to use when the reader cannot tell what one row represents or which document explains a code. Write the README against the actual package, then check every filename and relationship you describe.
Follow the repository’s requirements and the permissions governing the material. This guide concerns explanatory writing for an established dataset package. A README does not establish that material may be shared, that a dataset is complete or that an analysis is valid.
Choose the orientation a new reader needs
Start with the collection’s purpose and scope. Explain what kind of material the files contain, the period or coverage where relevant, and any important exclusions. Distinguish the material supplied from the wider study that produced it. A paper may discuss interviews, for example, without its accompanying package containing interview recordings.
The UK Data Service’s data-level documentation guidance, checked on 3 November 2026, emphasises explaining file contents, internal structure and relationships. Use that principle to help readers navigate the particular package you have checked, rather than presenting a generic inventory as proof of documentation quality.
Identify a sensible starting point. A reader should be able to locate the overview, the data files and the document that explains their fields. If the repository supplies a persistent identifier or a required citation, copy the verified details accurately; do not invent an identifier for a planned deposit.
Work through an original fictional file map
The following package is invented teaching material. No pamphlets were collected or indexed, and no files or deposit are supplied with this exercise.
Imagine a fictional package about references to places in a small pamphlet collection. Its checked inventory contains these four files:
| Filename | What the README needs to explain |
|---|---|
README.txt |
Overview and route through the package |
pamphlets.csv |
One row per catalogued pamphlet; pamphlet_id identifies the item |
place_mentions.csv |
One row per indexed mention; pamphlet_id points to the corresponding catalogue item |
field_guide.txt |
Field meanings, code labels and conventions used in the two tables |
A useful opening could say:
Begin with
pamphlets.csvfor the catalogue of items in this package. Useplace_mentions.csvto inspect the indexed place mentions associated with those items. The sharedpamphlet_idconnects a mention to its catalogue entry. Consultfield_guide.txtbefore interpreting the tables’ fields or codes.
That paragraph supplies a route and a relationship. It does not tell a reader that both tables have one row per pamphlet. A pamphlet may have several indexed mentions, so the tables represent different units of record. State those units explicitly instead of calling both files simply “the data”.
An absent mention record also needs careful wording. In this invented package, an item with no indexed mention is not automatically evidence that the pamphlet contains no place references. The README should explain the actual indexing scope and any unprocessed material. If that information cannot be recovered, mark the limitation rather than turning an empty result into a historical finding.
Put detail where readers can find and maintain it
Use the overview to direct readers to detailed documentation. It need not repeat every field definition from the data dictionary. Repeating definitions in several places creates more text to keep consistent when a package changes.
Describe relationships in enough detail to prevent an obvious misunderstanding: which identifier connects which files, what a row or item represents, and where exceptions are explained. Do not promise that an arbitrary merge or join is safe. Writing the relationship down does not test duplicate identifiers, missing records or the consequences of combining tables.
Where the package contains derived files, identify their inputs and point to the checked explanation of how they were made. Distinguish an original file from a transformed one without silently treating a polished output as the original record. Do not reconstruct a missing processing history from a plausible filename.
Check the README with the package it describes
Read the instructions from a new user’s starting position. Can you find each named file, identify what its records mean and reach the relevant field definitions? Check spelling, extensions and relative locations against the supplied version. Revise the map if a file was renamed, removed or split.
Then review the claims of coverage and access. Describe only what the checked package supports. Keep unresolved questions visible and follow the applicable repository or institutional process for them; an explanatory note cannot grant permission or repair missing evidence.
The data-dictionary guide explains variable-level meanings. The repository version-note guide helps describe an update after the files change. Keep the README’s orientation aligned with both.
