Make software tutorials that stick

Evidence-based ideas to make tutorials more effective

Learning is deeper and more durable when it’s effortful.
—Make It Stick

One of my jobs this year has been to develop a course on an abstruse standard about manufacturing systems. To prepare for the work, I read Make It Stick: The Science of Successful Learning, an accessible and practical book by cognitive scientists that synthesizes various studies in memory and learning.

While designing a course isn’t the same as writing documentation, the principles overlap. Tutorials, in particular, help people learn through practice.

Many of the principles from Make It Stick, then, also apply to making more effective tutorials. Here are the tips I gleaned to design a better learning experience. All quoted text is from the book.

Start with context

Start every tutorial with a small narrative that frames a plausible problem that can be solved by applying a new skill. As the tutorial progresses, your learner should actively participate in the construction of a solution.

Putting new knowledge into a larger context helps learning.

Skills and information are easier to recall if the learner can position what they’ve learned into a wider body of knowledge or memorable narrative. Plus, if the example is plausible and common, the narrative serves as a training simulation for the problems that the learner will meet in real-world contexts.

Have them try first

Before demonstrating solutions, give learners a chance to guess. In practice, you could do something as simple as starting a section with a true-or-false or multiple-choice question. Of course, with a little JavaScript, the possibilities get much more interactive.

Trying to solve a problem before being taught the solution leads to better learning, even when errors are made in the attempt.

Guessing makes learners think about the problem and primes them to pay attention to the answer. And as long as you have some mechanism to give feedback, an incorrect guess isn’t a bad thing: it’s an opportunity.

Making mistakes and correcting them builds the bridges to advanced learning.

Weave different tasks into the overall story

A long tutorial likely incorporates more than one task. Rather than order the tasks in sequence, interleave them.

When you’re adept at extracting the underlying principles or “rules” that differentiate types of problems, you’re more successful at picking the right solutions in unfamiliar situations.

For example, an introduction to SQL likely covers not only the SELECT statement, but also UPDATE, CREATE, and so on. The conventional approach proceeds sequentially, exhausting all there is to say about one topic before turning to another. The more effective approach weaves these topics together. For example, the tutorial might teach learners first how to select a table, then update it, and then create a new table before finally rotating back to SELECT to query the new data.

Learning is more effective when the learner has a chance practice working on the problem domain from various angles. This strategy also has the added effect of providing spaced recall.

Reincorporate old information

As the tutorial progresses, revisit topics that you introduced earlier.

Retrieval practice—recalling facts or concepts or events from memory—is a more effective learning strategy than review by rereading.

Even if the tutorial doesn’t last long, a little bit of spaced repetition can help the learners retain important aspects of it their long-term memory. Recall is a critical part of applying skills, but you have to stop thinking about something in the first place to recall it later.

Together with the interleaving technique, spacing information out helps the learner adapt the tutorial to their problem.

if you space out practice at a task and get a little rusty between sessions, or you interleave the practice of two or more subjects,retrieval is harder and feels less productive, but the effort produces longer lasting learning and enables more versatile application of it in later settings.

Build a mock test at the end

A small assessment at the end can help reinforce the concepts. This is the second layer of retrieval practice.

In virtually all areas of learning, you build better mastery when you use testing as a tool to identify weaknesses and bring up your areas of weakness.

Testing in this case is not about trying to assess whether the learner knows something; it’s about helping learners remember and avoid a false sense of mastery.

Ask the user to elaborate

After giving them a chance to practice, ask the learners some questions to get them thinking about how the information applies to their wider body of information.

If you practice elaboration, there’s no known limit to how much you can learn. Elaboration is the process of giving new material meaning by expressing it in your own words and connecting it with what you already know.

Presumably your learners are taking the tutorial because they think the skill that it imparts might apply to some broader problem in their lives. Ask them to think about what that application is.

You could even add an input text field for answers. Even if no one reads their answers, the very act of writing to elaborate topic helps them assimilate it into their wider body of knowledge.

For learners and designers, more effort brings better results (and more effort)

A skill takes time to learn, and time is our most precious resource. Things that are easy-to-learn are appealing objects of our attention. Ironically, though, what’s easiest to learn is hardest to remember. Durable skills are hard-won.

However, designers of learning experiences can use these techniques to diminish the tradeoff between ease and memorability. Efficiently designed tutorials can be both inviting to the learner and challenging enough to help them retain the information. Of course, I don’t deny that designing tutorials in this way requires more effort on the part of the writer as well. But all things excellent are as difficult as they are rare.

The need to understand that when learning is hard, you’re doing important work. To understand that striving and setbacks, as in any action video game or new BMX bike stunt, are essential if you are to surpass your current level of performance toward true expertise.