Re: how to organize the DOM specs [Was: CfC: publish new WD of DOM Core]

On 08/22/2011 11:22 AM, Jonas Sicking wrote:
> http://www.whatwg.org/specs/web-apps/current-work/complete/
>
> I *always* used the much smaller document that used to be available here:
>
> www.whatwg.org/specs/web-workers/current-work/

I don't really understand your point here. If you used the smaller 
document presumably you could just have easily have read the relevant 
chapter from the larger document.

> When implementing a spec, the first thing I'd like to do is to read
> the whole spec front to back. This in order to get a sense for the
> various concepts involved which affects the implementation strategy.
> It is also important as it's required to review the specification.
> With a spec the size of, for example, the HTML5 spec, this is
> substantially more difficult. Not only does it take significantly
> longer to read the full HTML5 spec if all I want to implement is the
> pushState feature. It's also impossible to hold the fully spec in
> memory, even at a high level.

Why would you read the whole spec to implement features contained in a 
single subsection? Alternatively, why wouldn't you read the whole HTML5 
spec to implement web workers since there are normative dependences? It 
seems very arbitrary to base your choice of what is enough background 
information on someone else's choice of multiple files vs multiple 
sections in a single file.

> Small specs are absolutely more easily implemented and reviewed.

I think this is an illusion.

Self-contained features are more easily implemented and reviewed. There 
is no reason that a relatively self-contained feature can't be a section 
of a larger document.

Small specs encourage people - including the spec editors - to perceive 
that features are more self-contained than they really are, leading to 
the problem of important detail dropping into the gaps between the specs.

> Additionally, having releases of a spec makes it possible to know what
> browser vendors and other significant players agree on. A ever
> changing slowly evolving spec doesn't say what browser vendors agree
> is good as opposed to what the editor happened to have put in since
> the various stake holders took a look at it.

What browser vendors agree on is entirely unimportant to authors. What 
they care about is what actually ships. Once things are shipping browser 
vendors typically don't have much leeway to change things even when they 
all agree that it would be a nice idea.

We should fix the "authors need to know what is stable" problem by 
understanding it is actually an "authors need to know what is shipping" 
problem and implementing something like caniuse.com directly in the 
spec, with links to the relevant parts of the testsuite where appropriate.

Received on Monday, 22 August 2011 09:47:32 UTC