🏋️ Exercise: Exploring documentation methods & tools#
Objectives#
Take the time to explore and get introduced to a documentation method or tool
Get a feeling for the method or tool if it is something you can incorporate in your research workflow
Instructions#
We have compiled a list of different methods and tools for documentation of research data and code. Take the time to explore those which sound more appropriate for the type of data/software you work with in your project and reflect on the following:
Will this be useful for the documentation of your datasets?
What are the pros and cons of using this method/tool within the workflows of your research project?
Hopefully at the end of this activity you have found a useful tool(s) and/or method(s), which facilitates the documentation of the research data/software of your project.
ReadMe files for data(sets) - Generic way to document datasets or projects#
Download this template for a ReadMe file created by Cornell University: https://cornell.app.box.com/v/ReadmeTemplate
Adapt and start filling in the template to describe a dataset of your project. This could be an interview dataset, laboratory measurements, etc.
You are allowed to delete fields you do not need and add fields you think are missing
If you are unsure about the meaning of a component of the ReadMe file, go to: Guide to writing “readme” style metadata - Cornell University: https://data.research.cornell.edu/content/readme#best practices
Data Dictionaries - documentation structure for spreadsheet data or when collecting a lot of variables#
Watch the video about what a data dictionary is and what it looks like: https://www.youtube.com/watch?v=Fe3i9qyqPjo
Go to a tabular dataset you are working on or have worked on.
In an excel spreadsheet, start creating your data dictionary. List all the variables that you find in the dataset on column A. Then, add a clear and understandable description of that variable on column B.
Save the data dictionary in the same folder as your dataset as: Save the Data dictionary in the same folder as your dataset as: Data_Dictionary_DataSetName.csv
Electronic Lab Notebooks (for experimental data)#
TU Delft offers two different Electronic Lab Notebooks, eLABjournal and Rspace. Watch the short videos introducing them:
eLABjournal intro (4:11 minutes): https://www.youtube.com/watch?v=ys4BKEWWnEc&feature=youtu.be
Rspace intro (1:43 minutes): https://www.youtube.com/watch?v=q2CEnZRC1_o&t=5s
If after this exercise you would like to explore the notebooks in more detail, you can find the information on how to access them here: https://www.tudelft.nl/en/library/research-data-management/r/manage/electronic-lab-notebook
Data Package Creator - adding metadata to tabular data#
Click on the following links and keep the pages open:
Web interface of Data Package Creator: https://create.frictionlessdata.io/ - Note: this web interface is not suitable for using it with data that contains confidential or personal information!
Dataset example to be used in the exercise: E-night/Frictionless_Data_Fellowship
Listen and follow this demo video using: https://collegerama.tudelft.nl/Mediasite/Play/867c447d154147008489792118849c431d
CodeMeta generator - creating a metadata json file for software#
The CodeMeta initiative is a Free and Open Source academic collaboration creating a minimal metadata schema for research software and code. The academic community recommends adding a codemeta.json file in the root directory of your repository.
Click on the link to find the CodeMeta generator tool: https://codemeta.github.io/codemeta-generator/
You can fill in the metadata of your software project and generate a json file (machine-readable) that you can add to your repository