Christian Heilmann

⚡️But this is only for beginners, it doesn’t have to be that detailed…

Wednesday, December 19th, 2007 at 11:38 pm

One of the most annoying things to me on the web is new tutorials that are full of assumptions, bad practices and generally outdated. The irony is that when you tell the authors about the issues their excuse in a lot of cases is that the pieces are mainly targeted at beginners.

How does that make sense? Surely when you want to cater something for beginners nowadays you’d want to make it work for them today, and not base it on old technology and practices.

Catered for the audience

Back when I still had a television there was one public service ad in Germany I really liked: it was a man talking in baby talk and acting terribly silly. He then bowed down below the camera, you heard a slapping sound and he re-emerged with sticky tape over his mouth. The announcer then said “we need programs for children, not childish programs”.

This is exactly what we need for beginners: tutorials that are up-to-date, easy to understand and are based on best practices and proven concepts. Not tutorials that cover easy to explain concepts that actually don’t apply any longer or have to be un-learnt as soon as you become professional developers.

Web competence?

The main reason is that it is hard enough for adults to learn things, but even harder to un-learn them. It is hard work to go through the four stages of competence and once you are at the last you don’t want to start again. However, in a fast paced environment as the web becoming unconsciously competent can also mean that you just don’t realize any longer that there are changes you should be covering.

Lowering the barrier

The main reason people write tutorials that promise a lot and don’t deliver is that they want to lower the barrier of entry for new developers. This is a nice enough idea as web development with all its loosely defined standards and unknowns can be quite daunting at first. However, this to me robs beginners of the chance to become great developers.

My personal idea of a good developer is showing the urge to understand and apply – showing the dedication, interest and stamina to learn about the environment you apply your work, not only the technicalities of it. This comes with experience but it also needs to be based on a good foundation.

Leaving them hungry for more

A good beginner’s tutorial should actually not give beginners solutions but make them understand concepts and point to information they can use to learn things for themselves. There is no greater way of learning than finding it out by yourself, on your own terms and in your own time. Anything else is just repetition.

The why of beginner’s tutorials

There are several reasons why people write beginner’s tutorials:

  • They want to genuinely help other developers to come in and start learning the right way
  • They want to avoid people being scared of learning the job
  • They want a quick win – write about the easy stuff
  • They want to show off their skills to lesser skilled developers
  • They want to have a big audience – promising easy solutions makes for a lot of readers (think of tabloid journalism)

Not as easy as it seems

Now here is the tricky bit: writing a tutorial for beginners is actually a lot harder than writing about a more complex subject for a competent audience. The reasons are:

  • you can cause much more damage with bad information – people trust you to be an expert and will believe and repeat what you said
  • you will not get much constructive negative feedback – people will not dare to say you are wrong and the ones that could will not read what you wrote – as it is for beginners.
  • it is easy to start with a preconception of what a beginner is – however beginners could be people that are just coming from another area of expertise they are very competent in.
  • you don’t have a passion to work with – beginners are mostly scared or try to find a fast solution rather than true understanding

The last point is exactly what a lot of bad beginner’s tutorials work with and writing those will actually make it easy for you to get published. However, it will not make you a good trainer or writer, no matter how good the short term feedback and success is.

Danger signs

I know there will always be a lot of tutorials like this, as the number of hits / diggs and quick fame is important to people to make a name of themselves quickly, but I sincerely hope that this quick rant at least makes you reconsider doing another tutorial that starts with some of the classics like “XYZ in 10 minutes”, “quick solution for XYZ”, “ABC makes XYZ easy and fast!”, “You don’t need to understand XYZ when you do it the ABC way” or “XYZ in one line of code”.

Tags: , , , , ,

Share on Twitter