Organizing a CodeRefinery workshop

Anyone can organize a CodeRefinery workshop and teach the CodeRefinery lessons which are licensed under CC-BY. However, making it a successful workshop requires careful planning and preparation. Here we will go through practical aspects of organizing a workshop.

Email templates

A collection of email templates:

When adding new ones, add to an existing page (make a new section) or. Try to avoid too much markdown formatting, so that a rendered version can be copied to plain text email easily still.

Select a workshop coordinator

One or two persons coordinate the workshop preparation and debrief. This does not mean that they do all the work - they are encouraged to delegate tasks - but they make sure that nothing gets forgotten.

Other documents and references

Before the workshop

First steps

Lecture room

  • Start looking for an appropriate lecture room early.

  • See this list of requirements for the lecture room.

Set up workshop page

  • Import the template at to your username or the coderefinery organization, and name it like “2019-10-16-somecity”.

  • Update the required fields in and push the commits. The page should now be served at

  • If the workshop will be customized to the needs of a particular audience, modify the schedule accordingly.

  • If the workshop should be listed on

    • (Fork and) clone

    • Under, add a file named like which contains the fields permalink, city and dates. For example:

      city: Somecity
      dates: October 16-18, 2019
    • send a pull request with your new file.

  • Create a registration form following Indico event setup.

  • Open and test registration

Announcing the workshop

  • Twitter

  • Email persons who registered to notify-me form

  • Use local mailing lists and all channels possible

For self-organized workshops:

  • Write an email to to get a pre-workshop survey link and registration form on

Distribute the work

  • Make sure lessons are distributed

Preparing lessons

  • Go through the lesson material you will be teaching and think about how you intend to teach it, and how much time you will be spending on each episode.

  • Are there any unsolved issues that you can fix?

  • Go through the instructor guides of the lessons you will be teaching.

    • Review the intended learning outcomes, and try to keep these in mind while teaching.

    • Try to memorize the typical pitfalls and common questions.

  • Go through the lesson presentation hints.

  • Go through the helping and teaching guide, and request all helpers to go through it too.

Prepare practicals

  • Order catering (coffee, tea, water, fruit, something sweet, etc.)

  • Organize sticky notes

  • Organize extension cables if needed

  • Organize alternative wireless for those without Eduroam (if any)

Communication with participants

  • Send out practical information, including installation instructions, around 2 weeks ahead. Here is a template.

  • Emphasize that all software should be installed before the workshop starts, and point out the configuration problems and solutions.

  • Remind registered participants that they are either expected to show up or to cancel participation

  • Also ask those without Eduroam to speak up.

  • Maintain waiting list if needed

  • Make sure we have enough pre-survey answers

  • Close registration on the workshop page

1-2 weeks before the workshop

  • Workshop coordinator organizes a call with all instructors and helpers to discuss the schedule to leave no doubts about timing. Also discuss the survey results.

  • Point helpers (and instructors) to the tips for helpers.

Right before the workshop starts

  • Prepare a shared Google doc or with global write permissions, consider creating a memorable short-link (e.g.

Create exercise repositories

  • The collaborative Git lesson requires exercise repositories to be set up. For this follow the instructor guide in the lesson material.

Workshop preparation checklist

  • This checklist can be set up as an issue under or on another repository to keep track of the progress

    - [ ] reserve dates
    - [ ] decide workshop organizer
    - [ ] (online) prepare Zoom link or (in-person) book lecture room
    - [ ] announce (twitter, notify-me, mailing lists)
    - [ ] team of instructors complete
    - [ ] workshop website up
    - [ ] lessons distributed
    - [ ] prepare lessons
    - [ ] create exercise repositories
    - [ ] (in-person) prepare practicals (coffee/tea, sticky notes, extension cacles)
    - [ ] (online) Zoom roles distributed
    - [ ] registration open
    - [ ] team of helpers complete
    - [ ] registration closed
    - [ ] enough pre-survey answers
    - [ ] install instructions sent
    - [ ] pre-workshop briefing held, helper training
    - [ ] survey results shared with co-instructors/helpers

As participants arrive

  • Emphasize to participants that you need to sit with someone - don’t work alone.

  • Try to have participants sit next to someone with a similar operating system if they have no preference, since they will face similar problems.

Introduction talk

  • See

  • Have a 10 minute ice-breaker session where participants and instructors introduce themselves and either describe their research in 2-3 sentences or what they hope to get out of the workshop.

During workshop

  • While teaching, keep these tips in mind

  • Don’t start off with tech details, say why this is important.

  • Try to stick to the material, although some excursions are useful.

  • Keep up interactive feel by encouraging and asking questions

  • Keep time

  • For presentations which have shell commands, create a cheatsheet/reference on the board in real time.

  • Remind participants about sticky notes.

  • Make sure we take regular breaks (at least a short break each hour)

  • Give participants some time to also experiment (do not rush the classroom through exercises)

  • Encourage optional feedback at the end of each day or end of each lesson on sticky notes. Process the feedback immediately and adjust your teaching (pace etc) accordingly

  • Create GitHub issues for points which are confusing or problematic

  • Take active part even in the lessons you’re not teaching, e.g. by asking questions and (politely) interject with clarifications when you think something is confusing to the learners

  • Wrap up, say what you taught and why, and what comes next.

At the end of workshop


  • Process and distribute feedback to co-instructors and others (e.g. type up in shared document)

  • Debrief with instructors

  • Process certificate requests

Post-workshop survey

To measure the long-term impact of CodeRefinery workshops it’s useful to send out a post-workshop survey. This survey can identify which topics taught in workshops are particularly useful and which have less benefits for the participants.