buzz html5,HTML5 for Web Developers

While they’re essential reading material for our job, the W3C specifications are not exactly George R. R. Martin-level reading material. To make matters worse, the often-dry text (written for implementors, not authors) and…colourful illustrations come wrapped in a design straight out of 1999. While the W3C homepage got some lovin’ in 2009 from the dynamic duo of Happy Cog and Airbag Industries, the actual specifications are still only slightly above the baseline of browser defaults. So what’s a caring developer to do?

Ben Schwarz, a developer in Melbourne, Australia, took matters into his own hands with a userscript to give W3C specs some readability. Around the same time Mike™ Smith — the W3C team contact for HTML Working Group amongst other things — was looking for CSS help for HTML5: The Markup Language Reference, his cut-down reference version of the HTML5 spec. I was able to introduce Mike™ and Ben, and the result was HTML5 Edition for Web Authors. But this was only the start.

Ben then got on the WHATWG IRC channel:

Within 10 minutes of joining the WHATWG IRC channel Ian Hickson had granted me approval to continue with my own build of the spec, targeted for web developers.

After a lot of hard work, with input and encouragement from the web’s finest (including Dr Bruce), Ben has released HTML5 for Web Developers.

HTML5 for Web Developers

The focus of this specification is readability and ease of access. Unlike the full HTML specification, this “web developer edition” removes information that only browser vendors need know.

In addition to streamlining the content, it boasts all manner of freshly implemented buzzwords and technical trickery through the magicks of JavaScript and CSS:

find-as-you-type search (type “/”)

offline access

alternate styles for mobile devices

technical references pulled inline

beautiful typography

…and design

It’s been well received, with more than 20,000 uniques in the first 24 hours, and the Pied Piper of HTML5 remarking:

Enjoying the gorgeously readable presentation of http://developers.whatwg.org/ Nice work, @benschwarz.

The files to build HTML5 for Web Developers are on GitHub, so if you have any problems or suggestions add an issue. You can also fork the project and help out — I have!

…but what spec should I use?

In our previous article on “HTML as a Living Standard”, guest author John Foliot voiced a valid concern that with several versions of the HTML5 specification, you might end up on a different one than you expected, so let’s have a look at the different versions. Using the W3C nomenclature, “implementors” are browser and tool makers, and “authors” are web developers, and I’ve linked to Editor’s Drafts rather than Working Drafts, as HTML5 is still in flux.

The heavyweight specs

The HTML5 spec on the W3C site. It’s smaller than the other specs because several parts (including Microdata, Canvas 2D Context, and Web Messaging) have been turned into their own specifications.

The HTML5 specification (on w3.org)

I recommend this spec if you don’t follow HTML5 developments — e.g., if you’re not a reader of HTML5 Doctor. This is the specification being prepared for Last Call in May 2011, and it shouldn't change much from here on.

The HTML spec on the WHATWG site. It’s a superset of the HTML5 spec, including some things that the W3C has split into separate specs (see above). It also includes post-HTML5 features such as Web Video Text Tracks (WebVTT), but it doesn’t include non-HTML-specific specs like Web Storage, Web Sockets API, and Server-sent Events.

HTML — Living Standard specification (on whatwg.org)

I recommend this spec if you are interested in HTML5 (and beyond) and wish to be actively involved. While it’s more liable to change (especially the new bits), it’s also likely to include improvements that haven’t made it into HTML5. It’s also what browser makers are looking at. You can also get to it quickly with the link http://whatwg.org/html.

This is everything the WHATWG is working on, including non-HTML-specific material (see above). It’s introduced with a photo of a kitchen sink ;)

Web Applications 1.0 specification (on whatwg.org)

While this is pretty much the same as HTML — Living Standard, I don’t recommend it because it doesn’t have the ability to hide implementor details. However you’ll need it if you’re interested in Web Storage, Web Sockets API, and Server-sent Events. You can get to it quickly with the link http://whatwg.org/C.

Cut-down versions specifically for authors (us)

A quick reference for authors describing the syntax, structure, and semantics of HTML5. It's intended to be as concise and readable as possible. From the legend and self-styled W3C HTML5 jackass himself, Mike™ Smith, who also gets bonus points for the initialism “H:TML”.

HTML5: The Markup Language Reference (on w3.org)

I recommend this as a quick reference or cheat sheet to remind yourself of the essentials (well, in addition to the HTML5 Doctor glossary, of course ;-). It doesn’t have the depth of guidance or the examples in the other specs (or the implementor details), but it has info links to HTML5 for Web Developers, so you can easily get more detailed information.

HTML5 for Web Authors was Mike™ and Ben’s first collaboration. It removes the implementation details intended for browser makers and adds some style, and it’s more in line with W3C’s HTML5 in that it doesn’t include microdata. For the time being, it’s been superseded by HTML5 for Web Developers.

HTML5 for Web Authors (on w3.org)

I recommend this for JavaScripters, as it includes more API information than HTML5 for Web Developers. Currently it’s not as up-to-date as HTML5 for Web Developers, but I expect it to receive some love in the future.

HTML5 for Web Developers also removes the implementation details intended for browser makers, but includes some parts like microdata that have been cut from W3C’s HTML5 spec. I’m very impressed with the functionality and design, and I expect it to keep improving.

HTML5 for Web Developers (on whatwg.org)

I recommend this for anyone wanting a beautiful, readable version of HTML5. With local storage, it’s also perfect for adding to an iPad home screen. As it’s on GitHub, it’s also the only spec where you can easily contribute to the design and functionality.

There’s a bunch of other related Editor’s drafts linked to in the HTML Working Group sidebar which may interest you. Lachlan Hunt’s HTML 5 Reference — a learning rather than reference-focused version of the HTML5 spec — is unfortunately currently out-of-date and on ice, so I don’t recommend it.

In Summary

I think these specs all have their place. Personally I’ve been mainly using the HTML — Living Standard version, but expect to use HTML5 for Web Developers a lot now too. The differences between these different versions of HTML5 (except for H:TML) can be broken down into two groups: the extra modules they include, and whether they include the option to show/hide implementor details — the HTML5 and HTML specs both do.

One fear John Foliot expressed is that you might accidentally end up using something that was highly likely to change. The WHATWG HTML and Web Applications specs, however, have annotations indicating the status of each item in the margin.

Handy!

Addendum — a call to arms

More generally, Ben also recently wrote an article encouraging everyone to get involved in the web standards process. WHATWG and W3C are actively seeking feedback and suggestions regarding their work (as is Ben), and you can participate in various ways:

Read the spec and send comments via the HTML WG and/or WHATWG mailing lists

Contribute feedback directly on the HTML5 and HTML — Living Standard specs via the feedback widget

Contribute feedback via the W3 bug tracker (you’ll need a free account)

Join the HTML WG as a (self-)invited expert

Use recently implemented features in personal sites and give feedback

Write about your experiences using new features

Make demos to show new features (or, for the truly gifted, JavaScript mockups of proposed features)

Here at HTML5 Doctor, we’re doing our bit. I really hope you’re inspired by the backstory of HTML5 for Web Developers and see how low the barrier of entry is — inspired into action! We can (and should) all contribute to the future of the web.

I’ll leave the last words to Ben himself, who, a day after launching, said:

I'm thrilled to have it out, see good community support, and I hope that it becomes a reference for people to use every day

— Ben Schwarz