The WHATWG Blog

Please leave your sense of logic at the door, thanks!

Help us review HTML5!

by Ian Hickson in WHATWG

Are you interested in reviewing HTML5 for errors?

  1. Jump in! All feedback is welcome, from anyone.
  2. Open the specification: either the one-page version, or the multipage version or the PDF copy (A4, Letter)
  3. Start reading! See below for ideas of what to look for.

If you find a problem, either send an e-mail to the WHATWG list ([email protected], subscription required), file a bug (registration required), send an e-mail to the [email protected] list (no subscription required), or send an e-mail directly to [email protected].

If everything goes according to plan, all issues will get a response from the editor before October. You can track how many issues remain to be responded to on our graph.

What to look for

The plan is to see whether we can shake down the spec and get rid of all the minor problems that have so far been overlooked. Typos, confusion, cross-reference errors, as well as mistakes in examples, errors in the definitions, and major errors like security bugs or contradictions.

Anyone who helps find problems in the spec — however minor — will get their name in the acknowledgements section.

You don't really need any experience to find the simplest class of problems: things that are confusing! If you don't understand something, then that's a problem. Not all the introduction sections and examples are yet written, but if there is a section with an introduction section that isn't clear, then you've found an issue: let us know!

Something else that would now be good to search for is typos, spelling errors, grammar errors, and the like. Don't hesitate to send e-mails even for minor typos, all feedback even on such small issues is very welcome.

If you have a specific need as a Web designer, then try to see if the need is met. If it isn't, and you haven't discussed this need before, then send an e-mail to the list. (So for example, if you want HTML to support date picker widgets, you'd look in the spec to see if it was covered. As it turns out, that one is!)

If you have some specific expertise that lets you review a particular part of the spec for correctness, then that's another thing to look for. For example if you know about graphics, then reviewing the 2D Canvas API section would be a good use of your resources. If you know about scripting, then looking at the "Web browsers" section would be a good use of your time.

Staying in touch

You are encouraged to join our IRC channel #whatwg on Freenode to stay in touch with what other people are doing, but this is by no means required. You are also encouraged to post in the Discussion section on the wiki page for this review project, or in the blog comments below, to let people know what you are reviewing. You can get news updates by following @WHATWG on Twitter.

↔

17 Responses to “Help us review HTML5!”

  1. […] editor of the HTML 5 spec, Ian Hickson, calls for input on issues in the spec—typos, contradictions, or simply confusing bits. If everything goes according to plan, all […]

  2. It might be useful for reviewers to use one of the alternative style sheets mentioned a few posts ago:

    If you view [the HTML 5 specification] in a browser that support switching stylesheets (such as Firefox, under the View ? Page Style submenu), you can choose between “Complete specification” (default), “Author documentation only,” or “Highlight implementation requirements.” The “Author documentation only” stylesheet hides all of the client parsing algorithms and focuses on the elements, attributes, and scripting features that web authors need to know about.

  3. Sorry, I don’t really review anything, but I think there are 2 minor issues in the rendering section:

    1. Firefox, Opera, Safari and IE (8 and older versions) treat the fieldset element like a block formatting root/context as defined in CSS 2.1; Safari got a bug with collapsing margins in this case, but otherwise, the implementations of the fieldset element are identical.
    I think it should be explicitly mentioned that fieldset is to be treated like a block formatting root.

    2. Unlike CSS 1, CSS 2.1 doesn’t allow clear to be set on inline elements. Maybe it should be mentioned, that the br element is an exeption to that rule, because that’s how browsers implement it (probably becausde of the old br@clear).
    Both HTML 4.01 and HTML 5 suggest br to be an inline element.

  4. The section “8 The HTML syntax” describes that a HTML document must consist of a root element, in form of an html element.

    The section “8.1.2.4 Optional tags” describes that the html element’s start and end tag can be omitted.

  5. Francesco, the root element is still present in the document, even though its tags may be omitted from the serialisation. The start tags are allowed to be omitted for some elements because those elements are implied by other content. In the case of the html element, it’s implied by the presence of the head, which, if its tags are also omitted, is implied by elements such as title or meta, etc.

  6. Lachlan, thanks for the interesting info!

    Nonetheless my understanding of “in form of an html element” is that I have to write . It just confused me a little bit.

  7. Sorry for that. I meant: “…is that I have to state explicitly the html element.

  8. So is the job mainly to spot spelling mistakes, bad grammar, nonsensical sentences, rather than question the specs as well?

    I would be happy to help out either way.

  9. Jason: Either is good, it’s just that spelling is often easier for people to catch, and I’d be telling people to wait on doing that. However, if you want to review the content itself, please do so!

    To everyone else: Thanks for the comments so far; I’ll be fixing the isues raised as soon as I’ve finished writing up the new “datagrid” API (should just be a few days, hopefully).

  15. […] Secondly, and most importantly, I haven’t had some kind of damascene conversion to the anti-HTML 5 camp. I firmly believe that it’s the best way forward for an Open Standard that allows us to write richer web pages and applications. And I’m sure that no-one, especially those in the Working Group, believes it’s perfect already. In fact, the Working Group consistently call for developer participation in reviewing the spec. […]

  17. This is the 3rd time I start a HTML 5 project, and the 3rd time im not sure if the navigation breadcrumb should be a nav or not…. and the 3rd time i use lot of time, still wondering the same question…

    that said, nav is ambiguos as hell, or we use it for everything or we don’t.

    I think we need to address navigation as vertically and horizontally.
    Vertical navigation is about different sections, example of google : [web – images – news – etc] while horizontal navigation is about getting deep in the page. example of google [news – science – united states – etc] that will benefit authors, developers and screen readers – A LOT!.

    There’s no such thing as major navigation in real world webs. there’s navigation. One that change your sections (major) and other that goes deep in a page. but also, the home link in a breadcrumb is a major navigation but isn’t vertically.

    There’s no place in whole HTML5 to create breadcrumb navigation which is really usefull for bots, users, etc. I think, breadcrumb nav should be addressed in a proper way.

    Hope it helps.

    6 years of heavy (x)HTML / CSS developer

    Greetings,
    Bart.