Don’t buy the pig in the wig or “why most JavaScript tutorials still suck”

I think we all have realised it by now JavaScript is a hot topic again and if you know your stuff and play your cards right you can make money and gain fame with publications (books, articles, magazine submissions) and conducting trainings and workshops.

This is grand and there is no reason why JavaScript should not be an integral part of web application and web site design – if used in an unobtrusive manner and with maintenance in mind .
However, lately I’ve discovered that there are a lot of publications cropping up that have been rightfully forgotten and got a lick of paint and the label AJAX just to be sold again without really looking into upgrading them.

You find terrible examples of convoluted JavaScript that was needed in the high time of the browser wars in these books and articles. You also find examples using technologies that are simply not logical to use and actually have proven time and time again to be more destructive than helpful for the usability of your product.

Bad examples

My favourite example of this was published in a book 2006 is using a select box as a site menu via an onchange handler on the select box and by modifying the document location. This kind of menu is impossible to use for someone who uses a keyboard and doesn’t know to press Alt+Cursor Down to expand the whole menu first. The normal keyboard usage pattern of a select box is that you use cursor up and down to navigate it and a menu like this will fire the redirect every time you go up or down. The example was even worse by not providing a submit button at all (how would a user without scripting submit the form?). Instead of explaining these problems the workaround was to offer a submit button wrapped in a NOSCRIPT tag as only users without JavaScript would need one.
It got worse by introducing document.write() as a viable way to write out page content with JavaScript (and by that mixing presentation and behaviour and making maintenance of the page a nightmare) and trying to detect the browser in use by reading out the user agent string.

While this clearly was a case of laziness and trying to sell an outdated product with a new packaging (pig in a wig with a bit of lipstick) there is a more fundamental problem that could also be the cause of this kind of tutorial: it is much easier to teach somebody outdated JavaScript techniques than modern DOM scripting.

Teaching syntax vs. teaching the use of a language

The problem is that if you want to explain the basics of a programming language most tutorials start with the syntax. This has been a convention for a long time and actually stems from teaching people human languages. Many people learnt a foreign language in school that way and are perfectly capable of reading and writing it but fail completely in pronounciation or engagement in a conversation. Ever wondered why you learnt much more about the language in those two hours talking to a charming and gorgeous foreigner (most of the time of the other gender) than in three years in school? It is about interest and determination.

Teaching people how to communicate in a foreign language is a much harder task than teaching the grammar and vocabulary. You need a lot more engagement from the person you teach and you need them to be interested in the language and using it. Most school education is seen as a “mustâ€? rather than a “I’d like to learn more about thisâ€?.

Some good language teaching techniques

I was lucky as I had an English teacher that made us subscribe to Newsweek, read the articles and then have a free debate in front of the black board. The roles of the different celebrities, politicians or other famous people featured in the news article were played by different students and one student had to be chairman of the panel. It was no coincidence that the teacher also ran the drama club.

This roleplaying made us become much more self-assured in using the foreign language than any long-winded grammar and syntax lecture would have done. Using the language became fun and you wanted to engage more. For example you wanted to learn more about using the language when you really liked the persona you had to play and wanted to get its point across in the debate.

Another good game we played was “just a minute”. You were asked to talk for one minute about a topic the teacher told you. The class was divided in two groups and if you managed to finish the minute your half got a point. The snag was that you had to avoid mistakes like hesitation, repetition, deviation and using your native language. If you were caught committing one of these crimes the person from the other team that spotted it was to go on and would get the point for his or her team. This technique taught you how to stay on topic and how to paraphrase a word you don’t know instead of feeling inadequate for not knowing it (as hesitation was a crime).

How does that relate to programming languages like JavaScript?

Not quite the same but similar ideas apply to teaching a programming language. When you teach the syntax and theoretical “hello world” examples you will breed non-creative developers who consider any change in the language a threat as they have to change their ways.
The practical upshot is that you can easily explain the language and give examples that lead to immediate results for those you teach the first few lines of script. Telling them to use document.write() to print out results of a simple addition gives an immediate satisfaction that they achieved something, much like a


10 print "hello";
20 goto 10


back in the days of long ago.

The inaccessible dropdown menu navigations shows how to handle forms, the browser location object and event handling in one step, which allows the readers to play around with almost everything the browser offers them.
This satisfactory feeling leads to great feedback and also leads to publishers asking for this kind of tutorial. I didn’t want to use document.write() at all in my book , but both technical editors demanded it as it is very handy to explain things with it. At least I managed to get a message in that it is outdated and should be replaced with other techniques.

The real way I’d have liked to start the book about JavaScript would be to explain what an HTML document is, how browsers function and what you can reach with scripting, and how the DOM allows you to navigate around the document.
Then I’d have explained the syntax options of loops, conditions and calculations and put the lot together in a lot of examples using events.

However, a book like that is much harder to sell as people leafing through the first few pages would feel cheated not getting immediate code examples. Our attention span is so short by now that it feels wrong to learn about the environment we are going to work in before we learn where to press the button to turn on the tool to manipulate it.

So in essence I can see ourselves being in a spot of bother: we know that some basic techniques are just bad and you don’t need them any longer if you want to create an unobtrusive and easy to maintain web product. On the other hand we also don’t dare to break conventions of teaching and assume from the very start that readers are not interested enough in a subject matter to take in a bit of theory or the not obviously related information.