I 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 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 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:

Please enter a number

The label element is needed to tell users what the entry field is and what they should do with it. The type 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 the id is needed to connect the label and the input element, the placeholder shows the user an expected value and the required 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 the value of the field with getAttribute() and setAttribute(). So if you want to use JavaScript to set the value of the entrynumber to 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 console.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 the entrynumber to 5, all you need to do is document.getElementById('entrynumber').value = 5. If you want to read the value of the field you can do a console.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.

My esteemed colleage Klaus Komenda seems to spend as much time as I do writing cool stuff for the masses, but somehow he doesn’t crop up in a lot of to-read lists. For shame, I say, pulling up my trousers until they reach my armpits (yes, I watched Simpsons) and I point you, esteemed reader to a series of articles explaining the YUI from ground up entitled Agent YUI:

• Get a lot of easy-to-understand YUI tutorials here

Yes, I am also taken with them as I like Bond a lot.

I am spending far too much time keeping explanation tutorials of scripts in sync with changes in the code. This is why I wrote myself a PHP solution to do the work for me. I’ve found over the years that the best way to explain a script is to :

• Show an example
• Show the full source code
• Show the source code bit by bit followed by explanations what each part does

If you go and check Tutorialbuilder you’ll see that I managed to automate most of this with a PHP script. It does the following for you:

• It generates the tutorial parts from comments in the script source code.
• It converts the source code to displayable code (encoding it, adding line numbers, allowing for lines to be highlighted)
• It creates a downloadable version of the script with a correct file name
• It creates an executable version of the script without comments to link to with a script element.
• It can minify the script (remove all whitespace to cut down on file size)

In other words, it turns this source script into a tutorial like this using a template and some CSS (most taken from the YUI).

It is not a replacement for JSDoc but instead catered to be easier to use and explain the functionality of code rather than the syntax of the JS code itself.

Tutorialbuilder is licensed with BSD, so go nuts using it for yourself.

Currently I am writing a lot of tutorials for an online self-training course about web standards and I ran into the annoyance of having to maintain example code in two places: the code itself and the HTML document with the explanations. Therefore I took jQuery and wrote a small script that automatically turns links to HTML code examples with HTML entities and line numbers. You can define which lines to display, which lines should be highlighted and you can add a live preview in an IFRAME when the link is clicked.

• Check out Ajax Code Display

When you write tutorials and you want people to use them wherever they are it is a good idea to offer the HTML documents as a zip for downloading. The benefit to the end user is that they don’t need to be online to look something up (I for example have the HTML 4.01 documents on my machine as HTML documents). The drawback is that the documents could be outdated without the user knowing – even when they are online while watching them.

Now, I pondered a bit about this and wondered if something like this wouldn’t be a solution:

• You add a version number to the title of each document.
• You add a remotely hosted versions.js script at the end of each document.
• This script has a JSON object with the version information of each document and compares the file name and version.
• If the version is outdated, it generates an error message that gets shown to the user.

You can try it out by downloading the two demo documents un-zip them and open them on a computer that is connected to the internet. The second document linked from the first one should be outdated.

The source of versions.js

(checkversion = function(){

// change as fit

var versions = {

‘documentexample.html’:’1.0’,

‘documentexample2.html’:’2.0’

};

var errorID = ‘versionerror’;

var errorMessage = ‘This document is outdated, please go to the homepage to download the new version!’;


	
// checking code

var d = document;

// get the version number

var cv = d.title.match(/(version (.*))$/);

// get the file name

var cn = window.location.href.split(‘/’);

cn = cn[cn.length-1].split(‘#’)[0];

// check and create error message if there is a mismatch

if(cv[1] && versions[cn]){

if(versions[cn] !== cv[1]){

if(!d.getElementById(errorID)){

var m = d.createElement(‘div’);

m.id = errorID;

m.appendChild(d.createTextNode(errorMessage));

d.body.insertBefore(m,d.body.firstChild);

}
	
}

}
	
}());

You could create both the titles and the JSON object in versions.js on the backend automatically by scanning the titles or from a version control system. What do you think?