Re: H:TML draft for FPWD consideration

Manu Sporny <msporny@digitalbazaar.com>, 2010-02-01 16:14 -0500:

> I asked some of the folks in our engineering team who do quite a bit of
> web development, but who are fairly detached from the whole HTML5 spec
> creation sausage factory, to take a look at this spec and the other
> HTML5 spec, side-by-side, to find out which one they would find more
> useful for day-to-day activity.
[...]
> * All of them wanted examples in the pages, demonstrating how to
> correctly use a specific element.

As I mentioned, I do still plan to add those. I also plan to
include examples that show some incorrect/invalid cases (because I
think users can learn from those too).

> * They complained that there was no type information, which is
> interesting. The type information is specified via a link - you can
> click on the type and go to another page, but it's not on the page
> itself. So they were unsure whether or not to put in a URL, text, or a
> specially formatted string (such as CSS) into the attributes for each
> new HTML5 element.

Interesting. I suppose I could address that by having the build I
use to generate the doc take the datatype descriptions and copy
them into the description for each attribute (instead of linking
to them). I guess that would make it more clear, but in some cases
it could also be a lot of repetition. I'll think about it more.

In the mean time, what I have done is to make the text of all of
the datatype links into prose. Previously, a number of them were
(somewhat opaque) pattern names from the RelaxNG schema that
defines them. I hope that makes a few of them a bit more clear.

> * One of the devs said that it would be nice if it were made clear what
> the best coding practices were for particular elements. Things like,
> "you should always include an @alt tag on an IMG element" or "you should
> provide an @id for H1-H6 to aid people that would like to navigate
> directly to the section on the page".

Again, that kind of usage guidance is something I've intentionally
avoided putting into this document, and something I think is much
better left to dedicated usage guides.

I the HTML WG wiki could be a useful tool in helping to develop
such a guide. To that end, I took some time today to update an
existing Guide that has been part of the wiki for a long time (as
part of the former "ESW" wiki that we migrated from recently), and
attempted to tweak it to focus it more specifically on being a
usage guide:

  http://www.w3.org/html/wg/wiki/Guide

There's not much content there yet, but it's a starting point at
least. Contributors who are interested in helping flesh it out can
add pages there for specific elements; there are couple them
started so far:

  http://www.w3.org/html/wg/wiki/Guide/e/body
  http://www.w3.org/html/wg/wiki/Guide/e/blockquote

And there's a template that can be used to make more:

  http://www.w3.org/html/wg/wiki/Guide/ElementTemplate

Other usage guidance can be added there -- guidance not restricted
to any particular element; for example, it looks like Ben Boyle
has been working on page that relates to markup for elements that
typically get formatted in italics:

  http://www.w3.org/html/wg/wiki/Guide/italics

If we get that guide fleshed out, I imagine I could eventually
have a Usage section for each per-element page of the H:TML
document, with a link to the corresponding element page in that
Guide (and other online HTML usage guides).

  --Mike

-- 
Michael(tm) Smith
http://people.w3.org/mike

Received on Sunday, 7 March 2010 14:00:54 UTC