Best practices for creating training materials

Posted by s.aragon on 28 June 2019 - 9:34am
Photo by RhondaK Native Florida Folk Artist 

By Niall Beard, Chris Greenshields, Sam Mangham, Louise Bowler, Mike Allaway, and Jess Ward.

This post is part of the CW19 speed blog posts series.

This blog post covers some of the important topics to consider when constructing training material.

A definition given for the aim of training:

“The Confidence to perform a task, repeatedly, to a defined standard in a timely manner.” -- Robin Hoyle, LearnWorks


What are the topics that you want learners to be confident in?

The goal of training is to make people competent outside of the room. To ensure competency outside, confidence is the most important thing to instil inside. If a GUI helps learners do that, go for GUI. If the command line makes them more confident, then do that. If command-line will likely baffle them and add to the cognitive overhead -- remove it.

When you’re developing training - ask yourself: will this make them more confident?

The focus should be to enable participants to work competently after the training course has finished. Training courses are of fixed duration so there is a limit to what can be taught. Of course, the author needs to prioritise what the participant learns within the time to equip them to work effectively after the training session/course. 

Creating tasks for the lesson

  • Completing tasks creates confidence

  • Which tasks, how long?

Learning by doing is an effective training method particularly with regards to software. Task focussed teaching allows students the chance to gain confidence in using software or developing their understanding in a focussed way. 


There are advantages and disadvantages to tailoring training material to specific domains. The advantages are that if the audience are all within that domain, the material will have greater relevance to their work. They will likely find the material more interesting and will have increased confidence in working through the material. 

The disadvantages are that domain-specific content may put off learners who aren’t within that domain, which limits the amount of people that can benefit from the material. By keeping it generalised, it will be beneficial to more people, which will likely get more “customers” (in a commercial environment) or more “contributors” in an open-sourced environment. This means that to make training material more sustainable, it can be argued that we should not tailor the content to a specific domain, unless there’s a large enough community of people within that domain who could benefit from it.

Making the teaching materials

Within the academic community, there are several starting points for training material relevant to software sustainability, with The Carpentries probably being the most well-known example. In more commercial environments, training materials are often produced from scratch. Starting from the very beginning can be time-consuming, with a guideline of 40:1 for face-to-face lessons and 400:1 for e-learning formats being suggested by one of our group’s contributors.

Follow-up maintenance of a course could take around 30% of that time again, if done around six months after first delivery. One suggestion was to “fix the software if it’s too difficult to teach”, which, while possible for small software projects where the instructor is involved in development, is unlikely to be practical for teaching standard tools such as Git and Python. But with the development of so many projects being open, we should encourage feedback to creators of tools where the documentation or syntax make their usage more difficult than necessary.

Setting up on the day

Once you’ve developed a training course, even after you’ve decided the format (whether online or in person, intensive workshops or long lecture course) the delivery is still an open question. A common, and admirable, goal is for the course to set the participants up for the future, to leave them with a working install of whatever tools and programs are required to make use of the knowledge they’ve learnt, and the low-level understanding required to set up again.

Fundamentally, however, this has its limitations; it clashes with the desire to make your training materials immediately accessible, to demonstrate a practical benefit immediately to hook participants in. Installing software, particularly scientific software, is often a complex process, and can leave users bewildered and on the back foot, having spent an hour or more following arcane rules they may not be able to understand and are unlikely to be able to reproduce. Worse, the sheer variety of systems users turn up with can lead to huge amounts of instructor time being wasted on the installation process. If every user has a different system, it seriously limits the ability of the participants to assist each other.

Instead, users can be introduced to the software and techniques more as a ‘black box’- replacing self-installation on a variety of systems with a single Cloud resource, or a bootable USB (a virtual machine image is also possible, but requires more technical skill). Instead of running code via the command line, introducing multiple challenging concepts at once, more familiar and less challenging GUI-based tools can be used. Even an expansive Integrated Development Environment like PyCharm can be absorbed more easily than learning how to run Python on the command line.

Share this page