Data Documentation
Research data documentation is a set of information that explains what the data contains, how it was generated, how it is organized, how to interpret it correctly, and under what conditions it can be reused. Data files alone, without context, variable descriptions, methodology, version information, or folder structure, often become incomprehensible—sometimes even to their own authors. Documentation is therefore a fundamental prerequisite for the reproducibility, verification, long-term preservation, and reuse of data.
What Is Research Data Documentation
Data documentation includes all accompanying information that allows the dataset to be quickly understood without the need for lengthy explanations.
In practice, research data documentation includes:
- README file
- Data dictionary
- Description of the variables
- Laboratory or field protocols
- Information on data collection or generation methods
- Records of transformations, version descriptions
- File manifest
- Checksums
Good documentation ensures that the dataset will be understandable not only today, but also in a few months or years—for team members, new PhD students, external collaborators, reviewers, data curators, and even for you. There is nothing “better” than spending tens of minutes trying to figure out what I meant back then. During data collection, we still remember the meaning of our own abbreviations and classifications, but without documentation, this “tacit knowledge” disappears at the speed of light.
Data Documentation vs. Metadata
Metadata
Standardized "data metadata" — such as the dataset title, author, date, description, license, identifier, and link to a project or publication. These are primarily intended for machine processing, searching, indexing, and interoperability in repositories and catalogs.
Data Documentation
It focuses more on human understanding and practical interpretation. For example, it explains the structure of folders, the purpose of each file, how data is collected or generated, data cleaning steps, changes between versions, variable definitions, and the relationships between files.
Metadata helps you find a dataset; documentation helps you truly understand and use it correctly. From the perspective of the FAIR principles , it is important to have both: metadata for discovery, indexing, and interoperability, and documentation for interpretation, reproducibility, and reuse.
README, checklist, manifest… what needs to be done
README
In common practice, the most important initial document is the README file. It is a concise but essential “dataset guide” that explains what the data contains, how it was created, how the files are organized, and how to interpret them correctly. The README is usually saved as README.md or README.txtso that it can be opened in any text editor even years later.
Data dictionary
And a description of the variables. This is especially important for table and database data. The BC README generator doesn't overlook this. You can include them directly in the README under the "Data-specific information" section.
File Checklist
To help users quickly understand what is in each folder and how the files are related. It is a practical, human-readable checklist that helps verify that the dataset is complete and that no important components are missing, such as a README, data files, a data dictionary, a license, scripts, or documentation. The checklist primarily answers the question: “Is the release package ready?”
Checksums
Checksums are cryptographic fingerprints of files (e.g., SHA-256) used to verify the integrity of data over time, after copying, transferring, or archiving. They are used to verify that files have not been corrupted or altered during transfer, archiving, or sharing.
File manifest
It differs from a checklist in that it is a specific file that describes the contents of a dataset package. It may include relative paths, filenames, file sizes, file roles, and checksums; it is also used after publication or transfer to verify that the dataset is complete and unaltered.
Fixity manifest
Simply put, it’s a 2-in-1 solution. It replaces both checksums and manifest files at once. (We’re currently working on a page with simple instructions for generating a fixity manifest.)
Citation and Licensing Information
How to cite the data and under what conditions it can be reused. The BC README generator takes this into account as well, so you don’t need to include this information separately outside the README file.
When to Create Documentation
Documentation should not be written only at the very end of a project. Best practice is to start at the beginning of the research and update the documentation on an ongoing basis as data is generated, its structure changes, new versions are added, or the analytical workflow is modified.
Ideally, the principle of documentation should already be reflected in the Data Management Plan (DMP). Among other things, the DMP must include information on data types, standards, and metadata; repositories; a sharing plan; long-term archiving; security; and responsibilities. If nothing else, a thoroughly prepared DMP will help with preparing the documentation for the dataset’s publication.
Need to get started quickly and easily?
Here you’ll find a page about README files, including a README generator that will help you create basic dataset documentation step by step. A README is the fastest way to capture the key context of a dataset and significantly improve its clarity and reusability. Give it a try. If you have a pretty good grasp of your data, it will take no more than 20 minutes, and you’re done.
Where to Store Documentation
The basic rule is simple: documentation should be stored alongside the data. The README should be one of the first files a dataset user sees, ideally located directly in the root directory of the project or dataset. If a project has multiple logical sections, you can also use multiple README files in individual subfolders.
Data documentation is not an administrative afterthought, but a component of good scientific practice. It helps preserve the value of data over time, facilitates team collaboration, supports FAIR principles, and increases the likelihood that data can be securely shared, archived, and reused.