Data only has value if you can interpret it correctly. That’s where documentation comes in. Whether you’re sharing data or just trying to remember what you did, documentation provides the essential context that makes data usable.
What to Document
Throughout your research process, make note of key details about your data, such as:
- Who collected, transformed, and analyzed it
- When and where you acquired it
- How you collected and transformed it – your tools and methods
- Units of measurement
- Definitions of key terms, abbreviations, acronyms, codes, and symbols
- Anything else that’s important to know
We often keep this essential information in our heads but memories fade over time. When in doubt, write it down. Future you will appreciate it.
Documentation Formats
- ReadMe files are usually saved as plain text for maximum preservability and should accompany a dataset whether it’s saved privately or shared in a repository. For more information, see Cornell University’s excellent ReadMe Guide, which includes a handy template.
- Codebooks or data dictionaries tend to be more complex than ReadMe files and often include tables and explanatory text. These are especially useful for datasets that require a lot of contextual information. For an example, see the codebook the Research Data Service created for the Morrow Plots dataset. If you’re publishing data with a codebook or data dictionary, it’s still helpful to include a plain text ReadMe file with the dataset citation and licensing information.
- Code comments are an essential form of documentation for any data that involves custom code. Good comments summarize what each chunk of code does in human readable language and ensure you can understand the code later on (because you will forget). They’re also a good place to link to sources you copied code from.
Helpful Tips
- Create documentation for clusters of related data files and include a list of those files.
- Store documentation with the dataset. It’s not fun when you have to dig through old emails to find essential information.
- Note equipment identifiers, software versions, and any settings necessary to replicate your process.
- The documentation published with datasets is often a fraction of the total information recorded. Make additional notes for yourself throughout the process, particularly when making transformations to your data.
- Never assume you’ll just remember everything you need to know.