Writing Teaching Materials
Last updated
Last updated
Once you have an initial draft of the exercises, you'll need to create example code, text, and other teaching materials that help your participants learn what they need to know to do your exercises effectively.
In the process of writing the teaching materials, you may find you need to go back and refine your exercises. It is an iterative process. But we recommend starting with the exercises because it helps you focus on teaching the core ideas needed for the exercise and not getting bogged down in every possible option, variation, etc. that might exist.
Most of the teaching materials should be code examples. You want people to be able to copy and paste relevant examples and change them to do the exercise. You copy and paste when you code -- so help your learners do the same.
If your tutorial is about using a tool with a GUI interface, most teaching materials will be you demonstrating how to do things. It can be useful to have written instructions of the steps you are doing though for learners to reference later (and so you remember what you're doing when you teach as well!).
If you can, execute code live rather than having the output already in the document. This will keep the session more engaging and interactive. Your participants can also execute the code on their own if they have a computing setup that will work for this. You can also pause to let people think about what the output of a given chunk of code should be before you run it.
Include code that may produce errors to show that these errors look like and common mistakes that cause them. But do mark this code somehow as having an issue so people don't get confused. Help normalize getting errors and working to fix them.
Instead of working through a multi-line example all at once, or a function call with a lot of arguments, try to build it up piece by piece, highlighting what you're adding each time. This will keep you moving through the file and prevent you from talking at a static screen for multiple minutes.
You can plan to include some live coding, but:
Have a script. I almost always regret deviating and showing something live that I haven't planned for in the middle of the tutorial because it opens up unrelated question and takes up time I didn't plan for. If someone asks a question that would require you to write new code to answer, save it for Q&A time at the end of the session. In the future, you can incorporate this code into the tutorial if you think it's important.
Keep it limited. There should be a reason why you're writing code from scratch rather than having the code already in the tutorial file. One good reason: demonstrating errors or mistakes.
Keeping up with live coding stresses participants out . They stop listening to you and start trying to write down code. Consider having a completed copy of what you're typing in the file for them to reference and take notes on.
While you'll have most or all of your example code already in your tutorial materials, this doesn't mean you can just execute it and expect people to follow what is happening. Plan to explain every element, especially in introductory tutorials: why is a comma needed? do you need a space there? Highlight different parts of the code with your mouse so people know which part you're talking about.
If you do include text in the teaching materials for people to reference later or to work through the tutorial independently, do not read this material when teaching synchronously. Text can be useful to have to keep yourself on track, remind you of the main points, etc. But no one wants to watch you read a file to them.