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

On Aug 22, 2011, at 11:47 , James Graham wrote:
> 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.
> [...snip...]
> 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.

I don't understand your point here. If you used the larger document presumably you could just have concatenated all the dependencies into one.

More seriously, if we don't want to rathole forever on this we have to collectively admit that any supposed rule about how people might review or edit a document based on its size or componentisation are, in the absence of hard data, just subjective bollocks. Different people read differently, different editors edit differently, and at the end of the day all you'll get out of such a discussion is a rehash of space vs tabs, vi vs Emacs, boxers vs briefs, etc. It doesn't matter that the truth is obviously on the side of space, vi, and thongs you'll still get no consensus.

What we *may* be able to come up with if we really intend to reach some form of agreement here is a set of best practices in document engineering. This would involve answering such questions as:

    • Is it easier for twenty editors to work on a single document or on twenty smaller documents? And by this I mean measurably — not personally.
    • What is the best way of capturing the dependencies that a testable assertion may have on other testable assertions, or on a set of defined terms, and does that best way benefit more from a given organisation of content or another?
    • What is the best approach with regards to patent policy (in a realistic world)? This must take into account such aspects as the political necessity of having multiple groups, time to Rec, feature-completeness of FPWD (since that's when the first exclusion period runs from), etc.
    • Several others I won't bother to list just yet.

If we can't be bothered with discussing this right then we should probably exit the rathole and leave it up to editors of individual documents. FWIW my personal experience is very much in line with Jonas's.

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

Right, but that's a non-sequitur to Jonas's point. Having snapshots of consensus that can be distinguished from whatever the editor just happened to braindump into the spec is very useful to anyone joining the conversation mid-way. The alternative is trawling through diffs and older thread which is error-prone, a barrier to entry, and conducive to permathreads.

-- 
Robin Berjon - http://berjon.com/ - @robinberjon

Received on Thursday, 25 August 2011 13:19:32 UTC