Tutorials suck
If you do any programming at all, you’ve done some tutorials.
They suck.
Maybe that’s a little harsh. More accurately, I mean that the value you get from tutorials is almost always somewhat limited unless it solves the exact situation you’re in. I’ve never done a tutorial that significantly increased my understanding.
I think in theory it’s possible to write a tutorial that doesn’t suck, but all the ones I’ve used disappointed me in one way or another.
A tutorial is like a cooking recipe, and unless you’re trying to cook the exact thing in the recipe, it’s not very helpful for much else. The recipe could tell you the steps, but often doesn’t succeed in telling you why the steps are there, how they can be applied to other dishes. If you’re lucky they tell you which steps are optional, or ingredients that can be substituted with something else.
It’s much the same with tutorials. Just a series of steps, which you follow mechanically but don’t understand. I don’t know if it’s the format of tutorials that makes it hard to explain things in detail, or if we as a profession have not figured out the best way to write a tutorial.
Let me give an example. Recently, I’ve had to write some C# on .NET for some reason. I don’t usually work with this technology, and this was a one-off project. I really did not want to install .NET on my Mac.
So I thought I’d use Docker. Go ahead and google “Docker C# .NET”, and one of the top results is this tutorial from Microsoft.
Now, I think this is a useful tutorial, and looks very well written. I don’t want to single out this tutorial as one that sucks. And I certainly don’t want to bash the authors.
It’s just that it didn’t tell me what I needed.
The tutorial starts off by… telling me to install .NET on my Mac, and then running a command to create the project. This was the exact thing I was trying to avoid! Why do I need to install .NET on my host computer when I could use a perfectly good .NET Docker container, whose image the tutorial says I’ll have to pull anyway?
I tried looking for other tutorials, and they all started with the same steps. No results for “generate .NET project using Docker”. Urgh.
Luckily I knew a little bit about Docker and knew that I could run commands on a container using e.g. docker-compose run service dotnet new console. I also knew about volumes, and if I used them, any files I generated from those commands would also be in my host machine. That gave me what I needed.
Sometimes, as in this case, you won’t find a single tutorial that tells you what you need. Instead, you figure this out by having some random facts floating around in your head and somehow connecting the dots.
That’s why I don’t envy anyone starting out programming. It’s completely insane how much know-how that is necessary to do your job is either undocumented, or documented poorly. Often what you really need is buried deep in some obscure part of the docs, and often scattered too.
Which is a shame, because often our first instinct would be to reach out to tutorials.
We either need to write better tutorials, or find some better format.