Re: There _is_ a DOM FAQ....

> The spec has become a Recommendation.

Yep. Sorry; I'm too used to typing PR-DOM.

>The spec also has an errata sheet which can hold clarifications.

We may want to think about what the proper division of labor is between the
errata sheet, the FAQ, and the tutorial, if all three will continue to
exist. One possible approach:

Normally I'd expect the errata sheet to only cover things that would have
been part of the spec itself if they'd been caught earlier. That includes
"This is a mistake in the spec",  "No, that isn't a mistake, we really
meant that," and additional definitions when it's unclear what the intent
was.

Much of what the FAQ needs to do is to provide a quick summary of and index
of the spec, for those who aren't language lawyers (no disrespect intended;
I put myself in that category), possibly with some context on why the WG
thought the more obscure features were a Good Idea.

And the Tutorial -- which I don't think I'd heard about before -- ought to
provide detailed usage instructions for the DOM, including warnings about
common coding mistakes... and perhaps some discussion of performance
issues.

For example, the spec says NodeLists are live. The Errata (and
lack-of-errata) document might say "Yes, we really did mean that 'deep'
NodeLists are live". The FAQ might reiterate that they're live, provide a
brief example to illustrate that, and point to the appropriate sections of
both spec and tutorial. And the Tutorial would be where we'd go into the
detailed advantages and disadvantages of this design -- which it can do for
you, what it can do to you, and how to maximize the former while minimizing
the latter.


Alternatively, we could start condensing these four documents into a
smaller set. The spec can't change without going through another approval
cycle, but the other three are editable.
______________________________________
Joe Kesselman  / IBM Research
Unless stated otherwise, all opinions are solely those of the author.

Received on Monday, 19 October 1998 09:24:57 UTC