Lesson plan 3: Documentation

FAIR elements:

Reusable

The ultimate goal of FAIR is to optimise the reuse of data. To achieve this, metadata and data should be well-described so that they can be replicated and/or combined in different settings.

R1. (Meta)data are richly described with a plurality of accurate and relevant attributes

R1.2. (Meta)data are associated with detailed provenance

Primary audience(s): Bachelor's, master's, PhD degree students

Learning outcomes:

  • Can explain the purpose (benefits) of the documentation, and its relation to FAIRness

  • Can identify different types of data documentation, and which are suitable to a specific discipline/domain

  • Can use existing documentation

  • Can modify existing documentation

  • Can identify considerations and strategies for documentation

Summary of tasks/actions:

  1. Introduce concept of documenting research data

    1. Outline that a key aspect of data reusability is that it is easily interpreted by people outside of the study, and that this can be achieved by proper documentation

  2. Link to relevant section/question of DMP tool used in your country/region (The examples used below are from the Canadian DMP Assistant, https://assistant.portagenetwork.ca/).

    1. What documentation will be needed for the data to be read and interpreted correctly in the future?

      1. Project-level

      2. File-level

      3. Item-level

      4. Any other contextual information necessary for others to interpret

    2. How will you make sure the documentation is created or captured consistently throughout the project?

      1. Clear articulation of how this will be done and by whom

      2. Standardised process for accurate, consistent, and complete documentation

  3. Depending on the discipline/domain of the group, introduce relevant documentation formats

    1. Readme file

    2. Data dictionary

    3. Codebook

    4. Commented code

    5. Lab/field notebook (including Jupyter Notebooks, R markdown, electronic lab notebooks, etc.)

      1. If introducing multiple formats, outline similarities/differences and use cases

      2. For each format that is showcased, articulate considerations and other important aspects by using exemplars and other material from the "References" section

  4. Conduct an exercise in which learners complete one or more of the documentation formats, based on course/project work that is relevant to learners. Blank templates can be found/created using material from the "References" section. Review and discuss challenges, as well as strategies to mitigate challenges.

References

READMEs

Data dictionaries

Codebooks

Commented code

Lab/field notebook

Exercises

PreviousLesson plan 2: Data management plans (DMP)NextLesson plan 4: Data creation

Last updated