Mess them up while they are young? Better web tutorials now!
Thursday, July 28th, 2011I am currently tech-reviewing a book that is used in educational environments (schools, universities, corporate training) on HTML5, CSS and JavaScript, or – in short – web development. And needless to say I am pretty shocked by what is taught in schools on that subject.
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
- that the comments are needed to stop browsers from displaying the code. The JavaScript line comment “//” in the last line is sometimes added “to make sure that your HTML validates”
If you really use an HTML5 Doctype none of them are needed. JavaScript is the only language browsers that support HTML5 and are in use will execute so the type attribute only makes sense when you want to embed a script that shouldn’t be rendered by all. Some client side templating languages do this. JScript is dead, let’s not even bother telling people about it.
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 LynxNetscape 1(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 document.write()
Every time I see a document.write()
or 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.
Using 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:
- Use
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
document.getElementById('result')
in your JavaScript will give you access to this element. You can read and write to this element by usinginnerHTML
. So if you do adocument.getElementById('result').innerHTML = 'My result'
you will see that the content of the paragraph is changed to “my result”. If you do analert(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 alert()
and prompt()
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 blur()
event handler using an alert and thus ending up in an endless debugging loop. Yes, it happens and it doesn’t make sense to go that way when browsers (and server-side JavaScript) have debugging tools these days that are much better in showing us what happens under the hood. A console shows us the objects and DOM elements rather than a cryptic [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:The
label
element is needed to tell users what the entry field is and what they should do with it. Thetype
attribute 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 theid
is needed to connect the label and the input element, theplaceholder
shows the user an expected value and therequired
attribute validates the form in the browser.As with all elements in the document you can reach the input field using the
document.getElementById()
method in JavaScript.and you can set and read thevalue
of the field withgetAttribute()
andsetAttribute()
. So if you want to use JavaScript to set the value of theentrynumber
to 5, all you need to do isdocument.getElementById('entrynumber').setAttribute('value',5)
. If you want to read the value of the field you can do aconsole.log(document.getElementById('entrynumber').getAttribute('value'))
You can set and read the value of the field by reading or writing to the
value
property of the element. To set the value of theentrynumber
to 5, all you need to do isdocument.getElementById('entrynumber').value = 5
. If you want to read the value of the field you can do aconsole.log(document.getElementById('entrynumber').value)
(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.