My vision for the perfect coding tutorial

Sandro Maglione

Sandro Maglione

Software development

How do you envision the perfect coding tutorial? 🤔

Lately I am exploring different methods and sources to get a sense of what's (best) out there:

  • Courses (and course platforms)
  • Video
  • Conference talks
  • Articles
  • Repositories
  • Documentation
  • API references

This is my vision and what I learned 👇

Without "why", "how" doesn't stick

During my years at University I had to follow some required courses. These were supposed to be introductory courses necessary to advance to more complex topics.

My thinking at the time was something like:

  • 👿 What? I don't want to follow this course, I have no interest in this topic
  • 😇 Well, maybe they know something and this will be helpful later on, let's roll with it

I came to the first day of lessons full of hype to understand how this course will help me later on, and the first things the would tell me are:

  • We will learn how to do this, this, this
  • This is the course schedule
  • This is the exam structure

Wait, what? You didn't tell me why this course.

Why is this necessary? How will it help? Why should I care? 🤨

Result: everyone cramming to learn as much as possible to "win" the exam and move on.

What about online resources

What about online articles without a "why"?

You can show me the best features, but if I don't know why and when these will help me, then the article doesn't connect.

And I leave to search something else.

Lesson: Make the "why" clear from the start.

Explain when a feature will be helpful before diving into how it works.

Curse of knowledge

The best practitioners may not be the best teachers:

Curse of knowledge: we incorrectly assume that everyone knows as much as we do on a given topic

In other words: When we know something, it's hard to imagine what it's like not knowing that piece of information.

Results:

  • Unconsciously skip fundamental steps/prerequisites (that we take for granted)
  • Less able to understand what's the key point that makes something "click"
  • Don't know if something is interesting or obvious

Lesson: ask for feedback from your ideal students.

Don't produce content without putting yourself in the same situations of your users.

There is more.

Every week I build a new open source project, with a new language or library, and teach you how I did it, what I learned, and how you can do the same. Join me and other 700+ readers.

"Cut it short!"

Aka show me the code!

I noticed many "wall of text" courses and articles.

These courses advertise how they provide "100+ lessons", "36h+ hours of content", and then you win the privilege to read an avalanche of words without a line of code.

My vision is a "code-first" course 👨‍💻

I show you how the code evolves and explain you why each line is necessary at each step

Imagine if each commit explains you exactly why something changed. You would be able to follow how a project evolves from nothing to a complete app.

Tell me a story

A great example I found recently is React for Two Computers.

Instead of telling me why server components are amazing and how to use them, the talk goes on the complete opposite path:

  • This is an example of a "vanilla" app (that everyone understands)
  • Wait, we have this problem here, how can this be solved?
  • We can try this, and this, and this. This looks way better and we solved the problem
  • Hey, look, we made a server component!

Brilliant!

This is the direction I am planning to go 🔜

Speaking of feedback: what do you think? What is your ideal tutorial?

I am working on "something" for a project that I'll share more about 🔜

See you next 👋

Start here.

Every week I build a new open source project, with a new language or library, and teach you how I did it, what I learned, and how you can do the same. Join me and other 700+ readers.