Writing Tutorials for Learning

Learning over problem-solving

A tutorial is a lesson that teaches someone how to use your product effectively. Tutorials turn people with little to no prior knowledge or experience of your product into users.

But while most of us pursue new skills in the hopes of putting them into practice one day, the purpose of a tutorial isn’t to solve a specific problem.

It’s to learn.

A tutorial may briefly touch on several topics to give the learner a basic understanding of a product or technology. It may not be what an experienced user would do, but instead simplified to make sense to a newcomer.

Mapping out the learner’s journey

Imagine that you’re drawing a map for someone. Before you can help them navigate, you first need to know where they want to go, and where they’re coming from. Only then can you determine the best way for them to get there.

Learning objectives

The destination, or the learning objectives, is the skills the learner gains by completing your tutorial. As a result, the quality of your tutorial depends on how efficiently the reader gains those skills, and how well they retain them.

Learning objectives are mainly a tool to help you design your tutorial. But they can also serve as a promise to the reader—if they complete your tutorial, they’ll walk away with these skills. By setting expectations early, they can determine whether this is the right tutorial for them.

Prerequisites

Even if we know where they want to go, the most efficient way to get there depends on where they are right now. Are they a junior developer? Have they used any of your other products before? Do they have experience with TypeScript?

To determine the best way to teach anyone, we need to understand what they already know. Unfortunately, individually assessing every learner at the start of the tutorial may not be feasible. But we can let them know whether the tutorial will be relevant to them, by listing the skills or tools we expect them to have before they begin.

For example, does the tutorial require specific tools or basic understanding of a related technology?

There, you’ve helped the learner figure out the skills they’ll have gained by the end of the tutorial, and whether it’s relevant to their current skill set. The next step is to figure out the most efficient way to best get them there.

Learning by doing

It’s tempting to think that the best way to teach someone, is to explain it to them.

It turns out, rather than passively reading or listening to someone, we learn things better by actively engaging with the material—for example by actually performing the skill ourselves.

We learn by making sense of things that happen to us and then adjusting our actions for a more desired outcome. By merely reading a text or listening to someone speak, we miss out on the feedback loop between what we did and what happened—and consequently, the opportunity to make a connection between the two.

If you want to learn how to play tennis, you’ll likely have more success by heading to a court and picking up a racquet instead of a book. After each ball you hit, you reposition yourself and try to hit the ball differently. Even better if you have an instructor with you to help you make sense of what you’re experiencing.

In other words, the best way to teach someone how to use your API, is to have them actually use it to build something themselves. Ideally, what they build should mimic the context in which they intend to apply what they learn.

Avoid having the learner build nonsense applications. While printing “Hello, world!” can be a step in your tutorial, it shouldn’t be the final goal. Instead, picture how they’ll be using your API and aim to replicate a real-life scenario.

Ok, but hang on. If the best way for someone to learn is for them to do it themselves, how do you get someone to do something they’ve never done before?

That’s where you come in.

Guiding the learner step by step

Being challenged to build an application using an API you just learned about can be scary for a new learner, who likely wouldn’t even know where to begin.

Break down the problem into smaller, more manageable challenges, each building on the skills or knowledge that the learner gained when solving the previous one. This lets the learner practice what they just learned.

For each challenge, the learner performs a series of actions to solve problems. They may need to sign up for an account, create an API key, install a client library, and then call the right functions. While they might be able to figure it out themselves by experimenting, by showing them how, through clear instructions, you’ll make better use of their time.

Guide them towards their goal by shining a light on what to do next.

Each set of actions the learner performs should have a meaningful outcome. But the learner might not understand the consequences of what they did. Your job as a teacher is to help the learner connect the dots. Which actions led to what results?

To guide the learner through the tutorial, repeat the following steps:

1. Tell them what to do
2. Tell them how to do it
3. Tell them what they did

Tell them what to do

Start by giving the reader a problem to solve. Feel free to use storytelling to explain why this is a problem worth solving. Try to find a balance between making it both exciting and challenging.

It’s time to share your app with the world. In this step, you’ll deploy your application to Foo Cloud using the foojs command-line tool.

Keep in mind that you’re asking the reader to do something that’s new to them. By introducing too many new terms and concepts, you risk intimidating the learner. They might think they skipped a step, or second-guess whether it’s the right level for them.

Tell them how to do it

Provide instructions using clear and concise language that is easy to understand.

1. In your terminal, run the following command to start deploying. This may take a few minutes depending on your internet connection.

   foojs publish

If the learner needs to perform multiple actions, consider using numbered lists to allow the reader to check them off and to keep track of where they are. If you’re switching between the browser and the code editor, it can be hard to keep track of your progress when all the instructions are hidden in a long paragraph.

Note that the amount and the type of instruction a learner needs depends on their previous experience. Experienced learners might instead only need a code snippet or a screenshot to understand what to do next. Make sure to match the type of instruction with the level of the learner.

Tell them what they did

Foo.js built your app and deployed it to your default region. Your app is now publicly available on https://your-app-name.foo.cloud.

After the learner has completed all the actions, they should’ve completed what you outlined earlier. By going through the motions themselves, they’re already building practical experience with your product.

Give the learner a chance to reflect on what they did, and what happened as a result.

• Help them understand what they did. Since they might not understand the consequences of their actions, you need to show them the connection between what they did and what happened. For example, “When you ran the INSERT query, FooSQL added a new row to the table.”

• Address potential issues or questions. In a classroom, the student can ask the teacher for help when they get stuck. Since you’re not there to help, try to address any issues that may prevent them from progressing.

• Celebrate that they’ve successfully completed the task you asked them to do. The feeling of doing something by yourself is empowering. Even if they merely followed instructions, they accomplished something—hard proof that they can successfully use your product to create something meaningful.

Providing the next steps

By the end, the learner should have achieved the learning objectives at the beginning of the tutorial. After completing your tutorial, they’ll likely have new questions based on what they did (or didn’t do). They’re now able to ask more complex questions and maybe even find information on their own.

At this point, the learner has a working application that uses your API that they can continue to tweak and experiment with, or ideally even use as a base for their own project.

While they might not be ready to take on another tutorial yet, they may eventually want to improve upon what they built. Provide additional resources that let the learner progress and learn about new features they can use.

Summary

This article has outlined a foundation for making tutorials aimed at developers. By integrating learning science into your developer content, you can improve both engagement from your readers, and how much they retain from it.

I encourage you to adapt the tips and examples to make it relevant to your audience and your company voice.

Stay tuned for more resources that will help you create better educational content for developers.