Why (MOST) Tutorials Suck

When was the last tutorial you’ve taken? It could have been my Free Email Course about Django REST Framework, or it could have been the “Official Django Tutorial” that will have you go through a simple Django Application.

What did you think about these tutorials? Which one helped you to learn the best? Why did it help you learn?

I’m not saying my course is the best, ever. Far from it. However, it was an experiment to see if tutorials can be better, or not.

This is an opinion piece about my feelings about tutorials and how it might be possible to make them better.

Tutorials Don’t Help you Learn

Tutorials don’t really help you learn how to use the technology that you want to learn. Every tutorials is an overview to show how the technology works, how easy it is to get up to speed, and gets you excited to read the documentation so you can learn more.

You will get a broad overview of the technology in question, and after you’re finished with the tutorial, you might try to create an app of your own. But, how well do you do? Does it work out? After creating the Polls App, how confident were you to create your own app?

“Type This Here then run it and see what happens”

Look at the Official Django Tutorial. Here is a small snippet of it:

Let’s write the first view. Open the file polls/views.py and put the following Python code in it:


from django.http import HttpResponse

def index(request):
    return HttpResponse("Hello, world. You're at the polls index.")

This is a typical example of, “Hey! Go to this page and type this here.”

Afterwards, it doesn’t tell you to run the application. The tutorial makes sure the application will run correctly before it tells you to run it. This is completely backwards.

There is A LOT you can learn by running the application at this point. You will get an error!! But, later, you’ll understand why you’re getting that error.

As an example, my email course had a few errors in it that you won’t know or understand until later in the course. I did this very blatantly. For the reader, it would be really hard to put 2 and 2 together and your understanding wouldn’t be as strong if you didn’t see the outcome of the errors. Then, also, you learned how to fix the issue!

It that makes sense, read on. I’ll show you how to make your tutorials better.

Fix your Tutorials, Here’s how

If you want to create a tutorial, here’s some things you can do to make it better for people to learn from.

Introduce them to common errors

While you are doing the, “Write this code here…” lessons, have your readers run the code so that they can see common issues. If the Official Django Tutorial told you to try to run the code after your created your first view, you would learn that in order for your app to work, you need a URL pattern to access it.

Imagine if the tutorial forgot to tell you to import a builtin Django function. Then, you ran the app. You’d learn exactly what error you get and you’ll be able to learn how to fix it.

Learning what common errors look like, you’d learn exactly what needs to be fixed in your app to fix the error.

FIX: Force your readers to see common errors. Over the course of the material, your readers will understand exactly how to fix them.

Let them figure some things out on their own

Don’t tell your readers everything. Let them do some work to figure things out on their own. That way, they will learn how to search for information and how to use the information to modify an existing application. That skill is indispensible.

One great way to do this, is to by creating Homework. Homework is a great way to have your readers learn the material better by getting out of their comfort zone and learn new material on their own.

This brings me to the third lesson.

FIX: Give your reader some homework to do. The ability to find information and know how to use that information to modify an existing app does wonders for teaching somebody how to use the technology you are teaching

Be available for feedback

If you give your reader homework, you HAVE to be there for questions and answers. Email works really well.

If you’re not there for feedback, you are leaving your readers behind. I tell everybody who takes my email course that they can email me their questions and I read and answer every email I receive.

FIX: Be available for feedback. If your readers have questions they deserve to ask you to clear up anything you are teaching them.

Give the application away so they can compare their code

It’s very possible that your reader is going to make some errors in their code and it’s going to be really annoying not knowing what happened that caused these errors.

Most of the time it’s a simple typo that can break the entire application. Try finding that typo in thousands of lines of code! In a simple tutorial with less than a few hundred lines of code, a typo is unacceptable.

FIX: Send your readers the exact code that you used for that lesson. This will allow them to check their code with yours. A simple diff my_app your_app will show you where your typos are.

Make bad tutorials better

So, if you’re going through a tutorial how can you use the above fixes to make it better while you’re going through it?

  1. Find groups of readers who took the tutorial so you can ask them for help and, if they are willing, their working examples of the project.
  2. Come up with some cool ideas that you want to implement and search the Googles for information about how to implement these ideas. Don’t wait for someone else to tell you what you should be implementing.
  3. Don’t be afraid to run the application midway through the tutorial. You can learn a lot by just reading error messages and attempt to fix them before you move on with the rest of the tutorial. Doing things by yourself is more important for your learning than simply copying code.

Excited to take your next tutorial? Sign up below for a free Django REST Framework tutorial!