[Content Review] Carpentries perspective

[SilkeGerlich]

This content review will be conducted through the eyes of the Carpentries. It regards the lesson and instructions in general

General review instructions

Where to start

• Browse the website that I have shared with you (Start here: site/docs/index.html) in Instructor View.
• Open the document's diffs of the pull request #1 (see list provided below), that corresponds with the site you are currently reviewing, in Githubs WebIDE.

Minor Changes If you find a typo or grammar mistakes, feel free to directly change them in the individual documents provided below.

Major Changes If you find larger issues with the content (representation, structure, clarity), comment preferably at the respective place in the pull request. Or use this issue for overarching comments or feature requests

While reviewing the content please also keep an eye on:

• spelling / grammar
• hyperlinks (all links should be active and open a new tab in your browser.)
• clarity / understandability
• site navigation

Through the eyes of an INSTRUCTOR :eyes:

Guiding questions

Keep these questions in the back of your mind, while reviewing the content

• Does the content comply with the overall Carpentries philosophy?
• • Does the lecture comply with the Carpentries guidelines for instructors and content representation?
• Is the lesson structure coherent, complete and comprehensive?
• Is the lesson content coherent, complete and comprehensive?
• Is the attached material complete, comprehensive and findable?
• As a Carpentries instructor, would you feel comfortable to give this lesson and / or include it in your curriculum?

Focus points

• lesson structure (silver lining)
• episode integrity
• integrity of instructor and learner content

List of documents for review

look at these documents in depth:

1. Landing page: index.md
2. Learner profiles: learner-profiles.Rmd
3. General Lesson Information: general-lesson-information.Rmd (metadata on top will be updated during the review :wink:)
4. Instructor Guide: instructor-guide.Rmd
5. Episode 1: getting-started.Rmd
6. Episode 2: data-metadata.Rmd
7. Episode 3: structure-schema.Rmd
8. Episode 4: enabling-technologies-standards.Rmd
9. Episode 5: web-locations-identifiers.Rmd

disregard these files as they are still under construction:

1. Acknowledgements: acknowledgements.Rmd
2. Meet the Creators: meet-the-creators.Rmd
3. Outlook - Linked Data: conclusion-outlook.Rmd will be included in lesson version 1.1

When you finish your review

• Head over to the pull request
• Check your tick box in the first comment
• Comment yourself, if you like :wink:

Good to know

If you have immediate questions or need a quick fix, use the review Mattermost channel or comment in this issue.

:heart: Thank your so much for you support in the reviewing process :heart:

[apirogov]

High-level checks against the Curriculum Development Handbook

• [X] clearly follows the Backward design principle / building course with target learning objectives in mind

• [X] uses elements of live coding and "didactic thinking aloud"

• [X] clearly defined target audience, learning objectives and key points

• [X] extensive instructor material

• [ ] not domain-specific / immediately relatable to scientists daily work but possible spin-offs could fit the content into various domain contexts

• [ ] Challenges are somewhat more complex than "typical" carpentries challenge (e.g. filling in blanks / multiple choice) but group-work based approach makes it more approachable. The provided challenges clearly try to put theory into practice i.e. putting it into a (different) context

[apirogov]

There is a wrongly rendered hyperlink in for Data & Metadata: (the &), probably its a problem in the pipeline:

[apirogov]

What is the difference between "data object" and "dataset" in the scope of the lesson?

The "example data object" is just a "dataset" with bad metadata, isn't it?

[apirogov]

Is the "instructor guide" using actually duplicated snippets from the other resources?

Ideally, this could embed from the other files.

[apirogov]

Some files are duplicated. Is this for technical reasons?

[SilkeGerlich]

What is the difference between "data object" and "dataset" in the scope of the lesson?

The "example data object" is just a "dataset" with bad metadata, isn't it?

Can you specify this question? If it is regarding the "example data object", then the "data set" does not apply (anymore). We've change the terminology to data object because dataset and data object can not be used interchangeably -> data set > 1 file. In connection with the example data object "dataset" would be an artifact, which I will have to get rid off. Please mark this in the .Rmds

[SilkeGerlich]

Is the "instructor guide" using actually duplicated snippets from the other resources?

Ideally, this could embed from the other files.

Good point! Yes, they are actual duplicates. Will try if this works with the pipeline (not sure, if the rendering works :) )

[apirogov]

Learner view: link to glossary is broken (if there is no glossary, remove? otherwise fix?)

[SilkeGerlich]

There is a wrongly rendered hyperlink in for Data & Metadata: (the &), probably its a problem in the pipeline:

Tried to fix it with different approaches but failed. Probably something in the pandoc pipeline. Will be included in the Workbench Beta-Test Feedback.

[apirogov]

What is the difference between "data object" and "dataset" in the scope of the lesson? The "example data object" is just a "dataset" with bad metadata, isn't it?

Can you specify this question? If it is regarding the "example data object", then the "data set" does not apply (anymore). We've change the terminology to data object because dataset and data object can not be used interchangeably -> data set > 1 file. In connection with the example data object "dataset" would be an artifact, which I will have to get rid off. Please mark this in the .Rmds

I disagree about dataset = > 1 file, see e.g. https://en.wikipedia.org/wiki/Data_set or https://www.oxfordlearnersdictionaries.com/definition/american_english/data-set

It says nothing about files, and in fact a single file with multiple pieces of information in my eyes qualifies as "dataset", i.e. a CSV file is a dataset

In any case one can argue if you have one JSON object of the same kind in a file, its not really a "dataset", so I see your point.

btw, I "fixed" all data set to dataset (did not know the other spelling is ok + carpentries always write dataset as one word)

[apirogov]

There is a wrongly rendered hyperlink in for Data & Metadata: (the &), probably its a problem in the pipeline:

Tried to fix it with different approaches but failed. Probably something in the pandoc pipeline. Will be included in the Workbench Beta-Test Feedback.

In the PR I suggested, you could also simply substitute & into and as a workaround (unless you have a strong preference)

[hofmannv]

i agree: a data set is not characterised by the number of files it is saved at. It is consists of multiple pieces of data (in one or multiple files) that are grouped according to some characteristic.

from HDO: definition "A generically dependent continuant which is composed always of multiple datum instances, which are grouped intentionally according to one or more common characteristics."@en rdfs:comment "Intention may be related to analysis, storage or publication of that data(set). For example, all files that are stored together on one CD-ROM or DVD might constitute a dataset as they are stored physically together. The organisation of the collection might strongly differ between application cases."@en

However i don't see a problem with calling the example data either example data, example data set or example data object (while the last one sounds like there is something more formal to it...).