Mess them up while they are young? Better web tutorials now!Thursday, July 28th, 2011
It annoys me that the first materials new learners get seems to repeat a lot of mistakes of the past. Following I will show some of the issues and what we should be doing instead.
Disclaimer: these are examples I did come across in current code examples and training materials. Anyone shouting that “nobody uses that anymore” and “what kind of idiot would code like that” should please take the stairs down from their ivory tower and get their hands dirty in real, day-to-day training that happens in our schools and corporate training rooms. I am not making this up – this is the impression people get when starting on the web from a school or corporate angle rather than reading magazines, blogs or follow some known people on Twitter.
The “hello world” from hell
The thing I keep seeing as the first code example is something like this:
This is normally followed by explanations that:
- this is the way to embed a script,
- that the type and/or the language is important to tell the browser what kind of script it is and
As for the comments, I haven’t come across any browsers ever that display the code inside script blocks. If you really worried about backwards compatibility that goes back to
Lynx(as apparently Lynx is still in production) then you should also not embed your scripts in the page.
In the end, this is what we will do in any case to reap the benefits of maintaining our scripts in separate files. Embedded code in a page is only needed for high performance environments that need everything in one cached file. The other time I keep seeing embedded JS code is to apply a quick fix to a product or to add a “one off as this is a special page” and thus making maintenance harder.
Let’s do this instead: the way to write a “hello world” would be to write an
index.html that explains the very needed basics of semantic HTML and embed the following:
That way people never get tempted to mix behaviour, structure and presentation and get to understand what it means to build a web product rather than a page that has everything in one file.
Of course, there can be benefits of keeping all in one document. For starters you can explain how the different things work together. In a real development environment, however, this is the odd one out and our primers should not start explaining those. It is much harder to un-learn things than it is to learn them, so why do we start with something you won’t use later on?
Let’s treat both CSS and JS like we treat images in an HTML document – an external resource. This is the biggest use case and it is the one we should get people to start with.
The curse of
Every time I see a
document.writeln() in materials these days I die a bit inside. I was around when we had to use that to write framesets into popup windows we just opened. The reason was that browsers didn’t support the DOM to reach content in the page or to create HTML content. I don’t want to remember those times, and neither should people who come into the world of web development for the first time.
I understand that it is the easiest way to show output in a document – to give new developers their first “wow, what I just programmed shows up on a screen” moment. I also know, however, that I would never hire anyone who uses
document.write just to print out something on the screen.
document.write() teaches developers that JS writes out content where you add a script node – not how to interact with HTML.
Let’s do this instead: instead of writing to the document we have a few options. These are ordered in preference, starting with the least desirable:
alert()– which is only marginally better, but comes with a few benefits. Alerts are disruptive. They stop the execution of your code and you can for example show how the value of a variable changes through the execution of your script. The issue with them is that if you want to show a lot of values, it can become annoying to hit enter to get rid of all the alerts. In new Firefoxes for example alerts are stacked instead of stopping the execution, which means that this benefit is gone.
- Start with a simple introduction to the DOM. It is really simple if you think about it:
Using the Document Object Model (DOM) we can reach elements in the page. Say for example you have a
in the document. Using
innerHTML. So if you do a
document.getElementById('result').innerHTML = 'My result'you will see that the content of the paragraph is changed to “my result”. If you do an
alert(document.getElementById('result').innerHTML)you will get an alert stating ‘my result’ as this is the text content of the paragraph after you changed it.
That’s not too hard, is it?
- Introduce debugging tools from the very start – explain consoles in browsers. All modern browsers come with a development console that can show messages written out with
console.log(). By starting with that we explain developers how to debug code before they write it and we let them see what is going on in their code. It is like showing a new trainee where the manuals and the first aid kit are before allowing them to use the power tools. Most of our job is testing our code – not writing it. In the real world we spend most of our time debugging and refactoring code – so why not start with this?
The curse of
Using alerts and prompts to print out results and get content from users is a simple way that works in any browser. However, in a real product you will hardly ever use an alert (other than for debugging) and I can safely say that I never saw the use of prompt outside of tutorials.
Hands up who ever made the mistake of adding an
alert() in a massive loop or try to debug a
[object object] as debugging information.
Let’s do this instead: instead of using the browser object model and alerts, confirms and prompts use the console for debugging and form fields for data entry. It is really not that hard to write a simple explanation how to access data in a form:
Forms in documents allow you to get information from the user and act on it. Say you have the following form in a page:
labelelement is needed to tell users what the entry field is and what they should do with it. The
typeattribute tells the browser what kind of entry field we expect – in this case a number. The name is needed for a backend script to get the information when the form is sent to the server and the
idis needed to connect the label and the input element, the
placeholdershows the user an expected value and the
requiredattribute validates the form in the browser.
As with all elements in the document you can reach the input field using the
and you can set and read the
valueof the field with
entrynumberto 5, all you need to do is
document.getElementById('entrynumber').setAttribute('value',5). If you want to read the value of the field you can do a
(after some testing and feedback from Mathias Bynens this still is the better way to teach new developers)
Back that up with a working example you link to and you already explained how forms work, what some of the attributes do, that browsers these days have client-side validation and how to read and write form values. And it wasn’t that long and hard to do.
The myth of the short attention span
Whenever I ask people to explain the why and not just the how in tutorials I get feedback that our readers are busy and want to see the outcome as soon as possible. The general consensus is that readers have an incredibly short attention span and don’t want repetition or get long winded explanations.
That may be true, but it doesn’t mean that you need to spoon-feed information. It means that the start of your tutorial must grab their attention and you must make it interesting. If going through a tutorial and coding along is fun then people will not realise how long they spend on a certain task.
Look at gaming: Angry Birds didn’t come with a tutorial – every time you get a new type of bird there is a simple picture showing you what they do and how to activate their special skills with your finger. They could have written a long document but they didn’t need to. If you really think people have a short attention span and lose interest really fast just see how many times people try to solve the same level over and over again as it is fun to see pigs explode. The same applies to “Cut the rope”. You feel bad when the little frog frowns as the candy gets lost and its constant excitement about the impending feeding makes you want to solve the puzzle all the more. Why do we have this attention only when it comes to “wasting our time” playing games?
Our training materials should learn from that and keep our readers excited and wanting to learn more. You don’t do that with dry examples of die throwing simulators and mathematical loops calculating prime numbers. Bring emotion into your materials or show real life examples and you will have the attention of your readers. In a training, have the group discover the materials bit by bit rather than giving them a massive binder with information and examples that need to be done by then end of the day if you want to get a shiny certificate to collect dust on your wall.
Lipstick and a wig on a pig
You can not re-use old materials by spicing them up with new technology. Period. Whenever a new buzzword appears, some old books get dusted off and new features get added. This happened with DHTML, then Ajax, then Mobile Web Development and now HTML5. Replace the Netscape 3 screenshots with Chrome ones, slap on a chapter covering the new techniques and voilá – you got yourself a new seller. I am sure a lot of people get approached by publishers to “write a new version of this old book, you, know, upgrading it”. Just say no!
Unless the original version of the book has been incredibly well written – and I have yet to find one of that calibre – this is a waste of everybody’s time and borders on a scam. In the past, a big part of web development was either working around bugs in browsers or catering for a special environment. Both are things of the past and you can’t just add a theoretical new chapter to upgrade an old book that is based on dated approaches.
We still struggle to find a correct way to build things on the web and our development practices change constantly. Performance issues, security concerns and stability are constantly fixed and changed in browsers and what was a great idea in the past can easily now get your site hacked or make it perform incredibly bad.
Changing the approach of explaining code in web development
All of this inspired me to write another beginners tutorial to web development. Instead of showing all the things that are possible we should show what makes sense and gets people on their way. A solid foundation with the least necessary information is a great starting point to go out there and learn on your own terms. Our tutorials and courses should start a desire to learn more – not to ensure we got all the information out that we were asked to shove down the throats of our students.