Instructor Notes
General idea
This lesson material can be used in a 1-day workshop in which participants work towards a reproducibility check by their peers at the end of the day.
In contrast with other Carpentries-style workshops the material is intended to be used entirely self-paced. Typically, a topic is introduced quickly, but then, participants go through the lesson material on their own pace, working towards making their own coding project reproducible, and learning as they go. Instructors and helpers can then walk around the (virtual) room and answer individual questions.
Pre-workshop assignment
episode 1: Pre-workshop assignment: Uploading a coding project to GitHub is intended to be finished before the workshop. Typically, the experience with GitHub is what varies the most between participants and this allows participants to learn about that in their own pace (or just upload their project to GitHub in a few minutes when they are already used to using version control). During the workshop we can then focus on making the code reproducible.
When you advertise the workshop it is important to make it really clear that the pre-workshop assignment is a mandatory prerequisite for the workshop. So: write it in the email title, write it in bold on the registration page, send a reminder! Also mention that you are available to answer question through email before the workshop. In our experience we achieve a 100% rate of participants completing the pre-workshop assignment.
Slides
You can find intro and ending slides in this workshop website of a previous edition.
Schedule
We recommend the following schedule:
- 09:30 Welcome & icebreaker
- 09:45 Workshop introduction: why is reproducibility important?
- 10:15 Software dependencies
- 10:30 break
- 10:40 Software dependencies continuation
- 11:00 Software documentation
- 11:30 break
- 11:40 Code conventions and modular coding
- 12:30 Lunch
- 13:30 Next steps: how to make your code reusable?
- 13:45 Work on your own project
- 15:00 break
- 15:10 Reusability check
- 16:15 Wrap-up
- 16:30 DRINKS
Pre-workshop assignment: Uploading a coding project to GitHub
Software dependencies
Document your research software
Instructor Note
Use these slides as a guidance.
The main purpose of this lesson is to make sure participants understand that DOCUMENTATION IS IMPORTANT. The goal is more to trigger participants then to teach them all the different ways one could document a project. It is good to communicate this (and that this will give more time for the other parts of the workshop).
Instructor Note
You can show the example documentation deployed on GitHub pages here: https://esciencecenter-digital-skills.github.io/good-practices-documentation-example/
Then, you can show that this content comes from simple markdown files, like: https://github.com/esciencecenter-digital-skills/good-practices-documentation-example/blob/main/doc/another-feature.md?plain=1
In addition, you can explain that with a few settings you can automatically generate documentation from docstrings. You can give https://nanopub.readthedocs.io/en/latest/reference/client.html as an example.