Tutorial Format

How to structure your tutorial materials

Your tutorial will consist of 3-6 sections, along with some brief introductory and concluding materials. Each section consists of an exercise, preceded by the materials you need to teach learners how to do the exercise.

Where possible, you want to create a single file that contains all of your tutorial materials: background, explanations, graphics, examples, and exercises. If you need to use multiple files, there should be one main file that contains links to other files; return to the main file regularly to reorient participants.

File Format

Notebooks when you can: For languages with a well-developed notebook technology (R, Python, Julia, Mathematica, MATLAB), we recommend you use a notebook. Notebooks allow you to include multiple types of information, learners can write and execute code in the file, and they can take notes in the same file they're learning from.

• Jupyter notebook for Python and Julia

• R Notebook or R Markdown file for R

• MATLAB Live Editor

HTML files: For tutorials that include code but are for a language without a well-developed notebook technology, a static html file can be a good option. If there's a fiddle or online tool available to use for exercises, you can link to those exercises in your file. HTML files also support code formatting and make it easy for participants to copy code from to paste into their own programs. Example: Regular Expressions Tutorial

Well-commented scripts: For programs where you and your learners will need a script file, create one with extensive comments. This may work well for programs like Stata or Bash.

Slides: Slides can be useful when teaching how to use a tool with an interface; for other types of tutorials, use one of the other formats above instead. Do not use slides for a typical presentation full of bulleted lists. Slides should have code, output from running code, screen shots, images of the tool, etc. You are not giving a lecture.

Note: we've found that code-heavy slides can be effective for teaching coding during in-person workshops where slides are displayed on a screen and learners still have their own computers to take notes and do the exercises. For virtual workshops, slides are more difficult because many learners do not have two screens or large screens, switching between programs can be hard, and it can be difficult to watch what's happening on Zoom and look at a code file at the same time.

Tip: Looking for a way to automatically create a html file with code and executed code output? R Markdown will process code chunks for bash, sql, octave, stata, sas, and many other languages. You don't need to know (hardly) any R to use R Markdown to create files for other languages. While this is a useful way to create an html file for learners to use, we don't recommend having participants use RStudio themselves during a workshop to execute code unless the workshop is about R, as having participants in a non-R workshop set up and run R/RStudio will be confusing.