Review of HTML5 document:
Here's a good example of a potential point of confusion for readers of
the spec when it comes to serialization:
In section 4.5.8 you introduce the ul element, and then demonstrate it
with a several child li elements, each of which is shown with an HTML
serialization.
In second 4.5.9, you introduce the li element, and then demonstrate the
li element using a serialization approach that would work with both
XHTML and HTML serializations.
And still later, in section 4.5.13.1, you again demonstrate li elements
using only the HTML serialization format.
In all of this is an implicit assumption of the capabilities of your
audience, that they understand the differences between the two. Yet,
this isn't stated as a prereq for the audience of the document. In fact,
you state that a familiarity with XML is helpful, but not required. And
as far as I've been able to see, though I may have missed it,
discussions about closing tags doesn't take place until section 8.
My suggestion would be to include both HTML and XHTML serializations,
carefully differentiating between the two. Or to provide separate
documents detailing the elements and their serialized form, HTML version
and XHTML version, if you want to inter-mix model and serialization
technique.
As for Section 8, that really is for user agent developers, only.
Seriously, I doubt you expect typical web developers or designers to get
much from this section. I would almost expect this to be a separate
document. What would be helpful is to bring this section up one level in
complexity, specifically focused at web developers/designers.
More later
Shelley
