I think if the [HTML WG] ends up delivering an authoring guide, it might likely be of more direct value to the wider community of authors and Web developers than anything else we produce.
— Michael(tm) Smith, 19 November 2008
The HTML5 spec is big. Really big. When formatted as a PDF for US letter paper, revision 3768 of the spec (the latest when I wrote this) weighs in at 662 pages. Not only is it big, but it’s full of complicated algorithms and other browser implementation details that even standards-aware web authors probably don’t care about. Because of this, there are several efforts—both within the working groups and without—to provide more easily digestible reference material on HTML5 for web authors. For instance:
- There’s a special “authors’ view” of the spec itself (available as an alternate stylesheet on the WHATWG’s copy or as a standalone document from the W3C) which hides all implementation requirements.
- Opera’s Lachlan Hunt has been writing an excellent authoring guide [HTML 5 Reference: A Web Developer’s Guide to HTML 5] within the HTML WG.
The HTML5 Doctor, run by
an outside group of web developers, aims to be a
resource that cater[s to] the people who wish to find out more about [authoring] HTML5…
If you’re a web author with questions about HTML5, I highly recommend taking full advantage of these resources.
Two of the HTML5 Super Friends (Jeffrey Zeldman in HTML5 For Smarties and Eric Meyer in HTML5 And You) have recently called web authors’ attention to what might appear to be another authoring guide effort, Michael(tm) Smith’s draft titled HTML 5: The Markup Language (AKA H:TML). With the extra attention the HTML5 effort is getting due to the Super Friends, I think it’s important to clarify the ways in which H:TML might not be the authoring guide you’re looking for. In fact, it’s not an authoring guide at all.
Both Zeldman and Meyer appear to believe Mike’s draft to
be a stripped-down version of the HTML5 spec. Zeldman describes
presentation of the spec, while Meyer says that it’s
version of the HTML5 draft with[…] implementor sections
stripped out. While it’s true that parts of
Mike’s document are
programattically derived from the spec, it’s not a
stripped-down profile like the authors’
view at all, but a separate spec which sets out to
define the elements and attributes of HTML5. Quoting Mike
The intent of it is for it to serve as a normative definition of the syntax and structure and semantics of HTML, without attempting to be an detailed authoring guide.
Aside: Whether or not
the HTML WG
[should] produce a separate document that is a normative
language reference is being tracked by the WG as ISSUE-59
Many object to publishing Mike’s document with normative
language in it, including participants from major browser
vendors like Mozilla
Several of these objections are like Henri
HTML5 spec] already normatively defines the HTML5 markup
language. It doesn’t make sense for the working group to
compete with itself by publishing two normative documents about
the same thing. Opera’s Lachlan Hunt explained
it like so:
This is a problem because it duplicates and restructures a lot of information from the spec itself, but not always by copying it verbatim[…] Since both would be normative, what would happen in the event of a conflict? Although, ideally, there shouldn’t be any [conflicts] by the the time they’re finalised, it’s still possible. In fact, it’s happened in one obvious case already. c.f. the repetition template attributes[…]
Håkon Wium Lie of
CSS fame thinks
this synchronization problem is unsolvable:
don’t think any amount of QA effort can keep two different
documents describing the same matter from being in conflict with
Don’t get me wrong—there’s a lot to be said
for H:TML as a document about HTML5. Many of the folks working
on HTML5 support publishing it as an informative syntax guide, including Lachlan
Hunt and James
Graham from Opera, Henri
Sivonen from Mozilla, and Maciej
Stachowiak from Apple. Mike himself said
not outside of the realm of possibility that we could eventually
end up deciding that it should only be informative and not
normative[…] I suppose that even if we were not to make it
normative, this document could also have some value as an
Personally, I really like Mike’s document—I’ve found it to be useful as a quick reference to HTML5’s elements and attributes (although Simon Pieters’s HTML5 Elements and Attributes might do a better job of that). I can imagine H:TML being a more accessible guide to the language for people (AKA assholes) who are used to reading documents written in the style of previous W3C specs. In fact, I think that might explain the appeal of H:TML to standardistas: they’re accustomed to using normative text (the HTML 4.01 spec) as quick-and-easy reference material, because contemporaneous authoring guides—such as the ubiquitous-in-search-results w3schools—are of such low quality. Unlike those dark days, we have several high-quality documents (listed above, and others) that standardistas can refer to as references while authoring HTML5.
I think it would be a mistake for the WG to publish H:TML with normative text in it. I’d prefer it to be reworked into auxiliary author guide material. Specifically, I’d love it if H:TML and Lachy’s authoring guide could be smerged somehow. I imagine Mike’s build system could be used to help keep the authoring guide in better sync with Hixie’s frequent spec edits.
In summary, while I applaud the HTML5 Super Friends’ efforts to bring about greater awareness of HTML5 in the web designer and developer communities, I’d prefer it if they recommended Lachy’s web developer’s guide to HTML 5 as reference material for standards-aware web authors.