@mmerlin, good point with the "gotcha's" . HTML by itself doesn't have many obvious ones, but there are common mistakes and omissions that are commonplace just from a lack of understanding.
A lot of these aren't obvious because "normal people" don't use non-visual UA's. See how folks don't use numbered headings properly, or think the only tags that go inside a TABLE are TR and TD... or the general lack of understanding what FIELDSET and LABEL are for.
But those aren't going to blow up in your face in terms of "normal" users. They just flip the bird at usability and accessibility. The only major hiccup I can think of is how I keep seeing people putting their charset META after content-bearing tags like other META or TITLE... a complete failure to understand what the tag is for and how browsers are supposed to treat it. Even there all that does is force the browser to start over from the top on parsing the page.
It's only once you get into building with CSS that things tend to go pear-shaped. Issues like some older versions of IE and FF screwing up positioning if comments (yes, the things that should be ignored) are placed between sibling-level elements; or the oft unwanted gaps between display:inline elements,.. but these things should have little to do with the basics and choices made in choosing tags.
@GrumpyYoungMan -- some parts are likely to be short, others not so much. One thing I've noticed -- I've been researching other guides -- is how convoluted they all get in terms of explaining the GRAMMAR of HTML, something that shouldn't even take a screen-height or two worth of text that they break up into 12 pages of four 1080p screen-heights each. That type of nonsense needs a trim.
I've had a few false starts already on this -- hence my looking for ideas -- where it keeps turning into a reference. I think this is because like @mmerlin I prefer a decent reference with actual examples over tutorials. But that's me, and I know after trying to teach others in the past that doesn't float for Joe Sixpack and Susie Sunshine. It's like how because I had been programming for nearly 25 years BEFORE I learned JavaScript, I was able to pick up the language faster and better than most using nothing more than one of the old pocket references.
Oh how I wish MDN's reference had been around when I was learning JavaScript.
But overall I do want to keep it relatively short -- around the same size as my "progressive enhancement" article. Five pages of what I consider medium length. I want to explain the basics and instill good practices, not get bogged down in the nitty gritty of each and every tag... though I'm afraid it might come down to that. It's bad enough I'm going to HAVE to waste four to six paragraphs explaining to people what a paragraph is! An image is not a paragraph. An INPUT and LABEL are not a paragraph. The contents of a TD are not a huffing paragraph!
Maybe just a mini-reference? Tag Name, operational level (inline, block), valid parents, valid children, valid attributes, one or two paragraph explaining its purpose, examples?
Anyhow, this is still off on the horizon, I NEED to get the website for Elementals 4 completed in terms of content. Site design and Elementals 4 itself has been done since October. I only just polished off the reference last week for everything but the newest iteration of DOM-JON, but I need to write up and explanation of how "views" are implemented (yes, it has views) as well as examples since E4 is a radical departure from E3, bringing it back to my original intent as I kicked all the bad advice and worse code previous "collaborators" suckered me into. This version needed to stay pure and stay strong.
Still, I might post some drafts for review as I go.