Instructor Notes

Expect varied audiences

We have run this workshop successfully with PhD students in the UK. Later-year computational PhD students say “I wish I had know this when I started my PhD”, and teaching these habits is the goal.

Learners will always have a mixture of backgrounds and skills, whatever their career stage. Based on their education, past research experience, past jobs, and hobbies, there can be a lot of variation. The goal of the material is that everyone has a chance to reflect on their practice and learn something valuable. Informally, if delivering this workshop saves 1 person from losing all their data, then it already made the world a better place.

Understand the learners by pre-workshop surveys

Pre-lesson (or even pre-episode) surveys are extremely useful to understand the level at which the learners are entering the lesson/episode. You could include these in the etherpad to help adjust your discussions to the learners. These questions are in the collaborative document template.

Understand the learners by discussions

The question for attendees “one thing you’re hoping to get out of this workshop,” in the collaborative document, is useful and diagnostic.

The discussion in the introduction episode is also useful and diagnostic. The learners’ stories about “What can go wrong in research computing?” and “What can go right in research computing?” tell you about their experience and gaps.

For example, this is usually a place where learners bring up stories of a time they lost their data or a colleague had a disaster. Instructors can tell their favourite (short) anecdotes about disasters or victories. The real lived experiences of instructors and fellow learners make this memorable, more than pre-prepared example answers.

What to skip

The manuscripts episode is skippable for earlier-career audiences (e.g. 1st-year PhD students) as they are far away from writing a manuscript.

The software-based project organisation template is too detailed for non-programmers so can be gone through very quickly or skipped. However, people who are already programming and finding it hard to organize their code may find it useful to spend more time on.

Discussions are the opportunity for peer to peer learning

Discussions are the structured opportunity for learners to learn from each other, facilitated by the material and instructors/helpers. In our experience, it is more effective if people learn from multiple peers than just from the instructor. Discussions are the instructor’s best opportunity to figure out where the learners are at and how to adjust the material accordingly.

Different approaches can work with different groups based on group size and time available.

Whole-group discussions

Can get everyone talking.

Small group discussions (breakout rooms)

We find small discussions of 2-5 people effective, at a table in real life in a breakout room online. Instructors/helpers can join these discussions if that’s helpful.

It is useful to ask these small groups to summarize their discussions for the whole group. Learners’ horror stories, such as “I lost a month’s worth of data because I hadn’t backed it up”, help to motivate. Their success stories, such as “I started scripting my data analysis and it saved me lots of time”, also help to motivate.

Collaborative document

We recommend as an efficient approach: ask learners to fill in their responses in the collaborative document, and the instructor can then read out highlights to lead and steer a group discussion. Collaborative documents are used regularly for Carpentries workshops (e.g. etherpad, hackmd, Google doc). It helps to set up the prompts in the doc first. Do we need to make a template for that in this repository??

In this lesson, using the collaborative document teaches the collaboration skills that we want to teach. This is especially important for the manuscripts episode, where the group collaborating in a document is an example of the “Single Master Online” approach and so leads learners to reflect on the process of collaborating.

There is a collaborative document template to paste into etherpad or whatever collaborative document you use. It includes reminders for a beginning-workshop hello, templates for the exercises, and template for evaluation at the end.

This lesson prepares learners for version control, but does not teach it

This lesson helps to develop the motivation for using version control, and the organisation and attitudes that support productive use of version control software. This lesson does not aim to teach version control, but instead aims to prepare users for a first course in git, such as the Carpentries git workshop.

If you have git users in the group, they may want to talk about how git solves all the problems. Be prepared to steer the conversations back to the material and suggest that learners take a git workshop in the future.

Collect feedback!

If you’re teaching in person you can use the Carpentries’ red and green sticky notes. There is also a section for one-up/one-down feedback in the Etherpad template. Remember to leave time for evaluation.

Please do file an issue on the github site summarizing the feedback, and feel free to file issues or pull requests suggesting specific edits as well.


If teaching from the website, make sure the font is big enough

Cmd + on mac, ctrl + on windows.


Data Management

Code and Software


Project Organization

Keeping Track of Changes


What To Do Next