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

On Mon, Aug 22, 2011 at 2:47 AM, James Graham <jgraham@opera.com> wrote:
> 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.

The point is that if it's just a chapter in a larger spec, how do I
know that there isn't other important information in the larger spec
that I have to read in order to get a understanding of the full
feature.

>> 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.

But how will I as a reader know if the feature is self contained or not?

> 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.

What people need in order to design good specifications is to have an
understanding of the web platform. If they don't have that then they
won't design a good spec. I don't see how merging specifications into
a larger specifications will increase their understanding.

In particular, they need to have an understanding of the features that
their spec is related to. We'll help them a lot more by making it easy
to research those features, than my merging specs together and hope
that that causes them to read more.

>> 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.

I'm not talking about authors, I'm talking about browser vendors. As
someone looking to implement a spec, I'm very interested in knowing
which parts of the spec has consensus and which ones doesn't.

/ Jonas

Received on Friday, 26 August 2011 04:49:38 UTC