The tutorial trap

A junior joined us in the spring having done three substantial courses. Not skim-watched, properly done: exercises completed, projects built, certificates somewhere.

Second week, I gave them something small and open-ended and they sat in front of an empty folder for most of a morning and then came and told me, in a slightly mortified way, that they didn’t know where to start.

They’d concluded from this that the courses hadn’t stuck, or that they weren’t really any good, or that everyone else has some quality they’re missing. And what had actually happened is much more boring than that, and I wish somebody had explained it to me in 2011 rather than letting me arrive at it slowly and miserably.

The competence is real and it’s borrowed

When you follow a tutorial, everything works. You type what’s on the screen, you refresh, the thing appears. You understand each step as it happens. The feeling of understanding is genuine and it is not a lie.

The trouble is what produced it. You were reading and recognizing, and recognition is enormously easier than production. Watching somebody make a decision and finding it sensible is a completely different cognitive act from making it, and the two feel similar from the inside, which is the whole problem.

Recognizing a good decision and making one feel almost identical from the inside, and only one of them is the job.

And look at what a tutorial removes. It decides what to build. It decides how to structure it. It names everything. It picks the libraries, sets up the tooling, chooses which of six approaches to take and doesn’t mention the other five.

Those are the skill. That’s what the job is. A tutorial is a recording of somebody exercising it, with the exercise edited out.

Nothing ever goes wrong

The second half, and I think it does more damage than the first.

In a tutorial, everything works first time. The versions match, the paths are right, the API returns what the author said it would. On the rare occasion something breaks it’s a scripted break with a scripted fix.

So you finish three courses having never once been genuinely stuck. Which means the first real error message, in your own project, at 9:30 at night, with nothing on the internet matching it, is your first experience of that entire sensation.

And it feels like evidence. It feels like the moment you find out you’re not one of the people who can do this, because the last 40 hours of learning contained no version of it. Nobody told you that being stuck for two hours is the ordinary texture of the work and that everyone with 15 years of experience is also sitting there going “what.” The tutorial’s smoothness has quietly taught you that smoothness is normal.

That’s the harm. Not that people learn less than they think, but that they draw a conclusion about themselves from the gap.

What to do instead

Not “stop doing tutorials,” which is the usual advice and is a bit smug. More like: change what happens afterward.

Do it once, then close it and rebuild it badly. From memory, without looking, accepting that it’ll be worse. Where you get stuck is precisely the list of things you didn’t actually learn, and that list is short and specific and you’d never have found it any other way.

Or change the requirements so you can’t copy. Do the tutorial’s project for a different domain: it built a recipe app, you build a thing for logging bouldering routes. Same shape, different nouns, and every difference forces a decision the author made for you.

Then build something you actually want. This is the one that matters. The reason a real project teaches more per hour isn’t that it’s harder, it’s that wanting the outcome supplies the decisions. You have opinions about what it should do, so you have to choose, and choosing is the thing you’re short of.

Finish something small rather than abandoning something ambitious. All the learning is in the last 20%: the empty state, the error case, the deployment, the domain name, the thing that broke on someone else’s phone. A finished ugly thing teaches more than three impressive half-things, and it’s the part of the process no tutorial covers because tutorials end at the interesting bit.

And read other people’s real code. Which is the oldest thing I believe about this and the subject of the first non-technical post I ever wrote. A real codebase has the decisions in it, including the ugly ones, and the ugly ones are the education.

What I’d hand somebody in week one

I’ve got this wrong repeatedly and here’s where I’ve landed.

Not a tutorial and not a sandbox. My instinct for years was to give a new person a well-defined, isolated task with the messy context stripped out, because it seemed kind. It’s useless. The context is the difficulty of the job, and removing it means they spend two weeks succeeding at something that doesn’t transfer, and then face the real thing anyway with less time and more expectation.

A real, small, low-stakes change on the actual codebase, shipped on day one. A typo in the footer, a copy change somebody’s been asking for. Not because the change matters, but because it teaches the loop: where the code lives, how to run it, how to get it reviewed, how it reaches production, how you know it worked. That’s five pieces of knowledge nobody writes down and none of them are in the source.

A named person, and permission with a number attached. “Ask me anything” is not an instruction, it’s a courtesy, and a new person will ration their questions because they don’t want to look slow. So I say a number: you should be asking me something roughly every hour for the first two weeks, and if you’re not, you’re either extraordinary or stuck and quiet, and I’d rather find out which.

Pairing, where they drive. If I have the keyboard, it’s a tutorial with a human in it, and all the same problems apply. They type, I talk. It’s slower and it’s much more uncomfortable for me, which is a decent sign it’s the right way round.

In defense of tutorials

Because there’s a version of this that’s dismissive and I don’t mean it.

They’re excellent at orientation. What exists, what it’s called, roughly what the shape of a thing is, whether this tool is even in the right category for my problem. They’re excellent for syntax you’d otherwise be looking up 11 times. And they’re good at getting a person past the terror of the empty folder, which is a real barrier and not a character flaw.

I’ve learned enormous amounts from them and I’d have got nowhere without them.

The trap isn’t the tutorial. It’s finishing one and mistaking the feeling for the skill, and then interpreting the gap as a fact about yourself.

I’ve fallen for it too

For the record, I did four courses on a thing in 2019 and cannot use it today, because I never once built anything with it. So I’m not writing this from above. I’m writing it as someone who has fallen for it inside the last two years and would like to have noticed sooner 🙃

They’re doing fine, incidentally. They shipped a tricky bit of the checkout last month. What changed wasn’t a course.