Sitepoint just released a HTML reference which is part of their plan to have a full reference on the trinity of web development (HTML/CSS/JavaScript).

Good HTML references are really hard to come by, either they are just listings, like W3schools.com or terribly outdated.

Sitepoint have done quite a good job in listing all the HTML elements and categorizing them into different use cases. There is also a list of deprecated elements and attributes to avoid (which could be considered dangerous to still bring up as some of them are too handy to simply add to solve an issue) and a Microformats primer.

I am working with other portals/article sites on similar projects and hope this will help flush old and outdated tutorials out of the search engine result pages.

The reference also gives a legend of browser support, something that so so far was only available on the German SelfHTML reference.

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?