README file generator
The README is a brief but essential “guide to the dataset.” It describes what the data contains, how it was created, how the files are organized, what the variables/units are, and how to interpret the data correctly. Its purpose is to make the dataset easy to understand and reuse by teammates, external partners, and the scientific community without lengthy explanations. After all, it may be useful to you if you return to the dataset in a few years.
A README is usually a text file (README.md or README.txt) that can be opened in any editor and is maintainable over the long term without special software.
Why does that make sense
1) It makes it easier to repeat and saves time for others and yourself
Without a README, users have to search for the meaning of abbreviations, file names, codes, units, or analysis parameters in articles or notes. This can take hours or days. Sometimes, the dataset itself may be completely unusable.
The README captures "tacit knowledge" (instrument settings, processing steps, QC, column meaning) continuously and prevents key details for understanding the data and the entire research from being "lost in translation."
2) It's a fast track to FAIR data (and more citations)
The FAIR principles (and from January 2027 also Act No. 328/2025 Coll.) emphasize that data should be searchable, accessible, interoperable and reusable. For data to be truly reusable, it needs rich documentation, licenses and provenance.
Documentation in the form of a README is ideal for this, as it supplements the limited repository metadata with practical instructions and necessary information.
3) Increases the chance of smooth data storage in repositories
Many repositories and data curators expect a dataset to have a description of its content, file structure, variables, and usage rules. A README will speed up publication and reduce the number of queries during curatorial review.
For data reuse, it is crucial to provide not only the "finished tables", but also information about how they were created. The publication itself is often not enough for this. The data can be also used for a purpose other than replicating published research.
When, where, why
When to create a README
It is best practice to prepare a README file at the beginning of a project/research and update it regularly. It is easy to forget important details later on. And if you leave it for last, you should create it at the latest before you publish the datasets or report them as a T-type result.
README is typically updated with every significant change: new file versions, variable modifications, pipeline changes, QC additions, or publication of a new dataset version.
Where to save the README
The README should be stored directly with the data so that it doesn't get "lost". The README file should be one of the first files a user sees for a dataset. The easiest way is to store it directly in the root folder of the dataset/project. If you have multiple README files (e.g. for logically coherent groups of files), store each README in a given directory.
It is generally recommended to simply name the README README.md (Markdown) or README.txt (plain text). I would recommend taking a few seconds to tweak the name a bit. For example: README_bc_[projectAcronym]_[DataSetName]_[yyyy]. Such a name will help with identification and assignment to a specific dataset. This file can simply get lost, like any other.
Why replacing README with metadata in the repository is not enough
Repository metadata is great for indexing and searching data. It's similar to a bibliographic record for a book. But README serves a completely different purpose. It makes the data reusable and interoperable. When someone finds the data using metadata and downloads it to work with, the README goes with it, still explaining the context and usage.
Therefore, it is crucial to have both: consistently filled in metadata in the repository and at the same time an attached README that describes in detail the file structure, variables, codes, processing, QC, etc.
What should a README file contain (recommended minimum)
1. Who / Contact: authors, institutions, email for inquiries.
2. What it is: a brief description of the dataset and purpose.
3. File structure: list of files and what is in each of them, relationships between files.
4. Methods: how the data was collected/generated and how it was processed from raw to analyzed (including tools and versions).
5. Description of variables: column names, definitions, units, codes for missing values, abbreviations.
6. QC and outliers: how quality control was performed and how suspicious values were handled.
7. License and citation: how to use the data and how to cite it.
README generator for biological data
1. This is a fully functional, but still testing beta version
Please excuse any minor shortcomings. I would be happy to receive any comments to fine-tune the generator. 🙂
2. Select README type according to dataset type
There are now 4:
Ecology / Biodiversity
Omics
Bioimaging
Laboratory experiment
If you are interested in other types, please email me and tell me which ones you would like, and ideally add the fields that should be included in the new README. Unfortunately, I can't work miracles, it will take a few days.
You can also use templates for other types of datasets. They will make your work much faster and easier.
1. Choose the one that best fits your needs and fill it in.
2. Generate a README.md and download it.
3. Give it a meaningful name (e.g. bc_README_projectAcronym_Dataset_v10.md).
4. Open in Notepad.
5. Delete, rewrite, add anything that doesn't fit your goal.
6. Ulož.
3. Add co-authors
You can fill in only the PI. You can also fill in all the co-authors of the research data to which a specific README file is linked. It is even desirable. Therefore, just click on “Add co-author”.
4. License assignment
Specify a license that says how others can use the dataset. The most common is CC-BY. This will allow other scientists to use it to its full extent, but they will always have to at least cite you as the author.
If there are any restrictions or time embargoes on the data that prevent it from being freely used, the "Access restrictions / ethical restrictions / embargo" field is the right place to describe this.
5. Outliers: rules & handling
It is possible to fill in Outliers for some dataset types.
These can be a measurement error (pipetting, bubble, saturation, bad well, instrument drift) or a real biological phenomenon. Without a description of the rule, no one will know.
Transparent description of outliers and QC is part of good data documentation (including definitions of codes/flags for low quality and outliers).
Recommended content for this field
1.Level: technical replicates / biological replicates / entire series / entire set.
2. Detection: e.g. “IQR > 1.5×”, “>3×MAD”, “z-score > 3”, “instrument flag”, “out of calibration curve range”.
3. Handling: I remove / mark / set NA / repeat the measurement.
4. Evidence: e.g. column qc_flag, outlier_reason, log in changelog, leave raw data unchanged.
Ex.
Outlier detection rule: “Within technical replicates, we mark an outlier if it differs from the median of technical replicates by >3×MAD.”
Outlier handling: “We discard the outlier well and calculate the aggregation (median) from the others. If <2 technical replicates remain, we set the value to NA and repeat the measurement.”
6. Data-specific information
Data-specific information is a part of the README file where, as the name suggests, very specific information is written. Moreover, this part may not be in the README even once, or it may be repeated many times (for each file, table, dataset, etc.). It depends on the circumstances and the content of the dataset. And the content of this part may be different each time. And my coding skills are not enough for that.
Therefore, the generator is set up so that if necessary, to fill in this part, just click on "Add Data-specific information". You can repeat it as many times as you need.
If this part is irrelevant to you, do nothing, leave it.
And what does this part include?
1. List of variables, including full names and definitions (give abbreviations) of column headers for tabular data
2. Units of measurement
3. Definitions of codes or symbols used to record missing data
4. Quality Control flags
Notes
7. Don't fill in what you don't need
None of the fields are set as mandatory by default. Even so, as many fields as possible should be filled in. However, if something is truly irrelevant, leave it blank. If the label is overwritten in the final file, delete it within 5 seconds of opening it.
8. Generate – review – download
After filling in the relevant fields, click the Generate README button. A preview of the entire file will appear. If you are satisfied with the content, you can download the file by clicking the Download README.md button. Or you can edit the fields in the generator and generate a new file. Don't worry, the filled-in fields will not disappear, you won't have to do everything from scratch.
9. Default README template for download
If you're not into these online toys, you can download the default template here. It's plain text, it opens in your browser. Highlight the entire text, copy it, and paste it into Notepad. It takes a little longer than using a generator, but it's still better than making a README from scratch.
README Generator for Biological Datasets
Select a dataset type → fill in the fields → generate a README (Markdown) → copy or download.
1) README metadata & general information
2) Methods — common core
3) Domain-specific information
5) Output (README.md)
Click “Generate README”…
README.md, open it in any plain-text editor or Markdown editor, revise the relevant sections, and save the file again.If you change the dataset structure, methods, files, or access conditions, update those sections at the same time. Always remember to update the README last updated date and the README version.