Beginner tutorials who don’t help beginners?

Today Smashing Magazine will released an article I wrote yesterday about a “beginner tutorial” on the same magazine which showed developers how to build a Christmas wish list whilst opening up the server to a lot of attacks.

It annoyed me that these things still happen, which is why I talked to Vitaly about it (I am on the expert advisor panel of SM) and he asked me to write an article to talk about the tutorial.

The beginner tutorial loop of annoyance

In general my point is that we are flooding the web with a lot of beginner tutorials, and a lot of them are nothing of the kind. Instead, they aim to make beginners feel good about a certain topic but fail to deliver knowledge. Instead, they oversimplify and try to pad with a lot of content in one tutorial. The reactions to these kind of articles are predictable:

• Seasoned developers will find issues with the code and claim that it should not be done that way
• Other people will disagree and tell the old men to stop telling young kids to get off their lawn
• Real beginners will chime in and say that they are very happy about the article and getting the feeling that things are not as complex as they seem to be
• A lot of fanboys will mention technology XYZ that makes this much easier
• The author will add more disclaimers about the nature of the code of the article in some edits and add warning messages about its viability in the wild – saying that this is just demo code

In short – a lot of back and forth and in the end the author will comply that the tutorial might be misleading and own up that the code should not be used in a live environment and explain. That doesn’t mean though that people will not do so, which is why I consider it very dangerous to cut corners when
writing beginner tutorials.

A call for real beginner tutorials

In the article I added a call for real beginner tutorials, as right now we keep falling into the same trap:

• We assume that only quick successes will make people want to learn things
• That’s why instead of explaining one thing we build a full solution with a beautiful interface, admin interfaces and a backend – omiting important features and warnings in each of them as we don’t want to overload people
• We release code that is not safe for release or real production quality – as it is easier to explain – and warn people not to use it in the real world – assuming that people do read and follow these warnings

The big fallacy is that we try too hard to give beginners a quick way in instead of allowing them to find out things on their own terms – which includes trial and error.

jQuery is not that easy to repeat

A lot of this is trying to repeat the success of jQuery when it comes to getting new developers to hit the ground running. The problem is that the success of jQuery is only repeatable when you do the thing jQuery did – replace the original technology with a simpler syntax and richer API. This is why it is much simpler to write a tutorial on how to use an API or package to achieve a task than to teach people how to start from scratch – the final goal is much closer and success immediate.

Quick success = lots of hits

The really annoying part about this is that simple and quick tutorials with a beautiful example are incredibly successful. They get a lot of hits, happy comments from beginners who think they learned something they can repeat and because of that online magazines who need the traffic to show ads will always be happy to publish them and deliberately ask writers to add more and omit the “complex stuff”.

Use the web to link to resources for beginners

We should not teach bad practices that are hard to un-learn for the sake of a quick win and click numbers. The web is already full of great resources we can keep up-to-date (yes, the Mozilla Developer Network being the biggest) and link to instead of repeating the same mistakes and starting from scratch over and over again.