Re: New split-out drafts

On Jan 8, 2010, at 5:51 PM, Ian Hickson wrote:

>
> All of these splits are very awkward. Just look at the "delta" spec
> nonsense in the microdata draft, where it tries to "fix" the rules for
> <link> and <meta>, or the way the rules in the Core spec have to  
> defer to
> the rules in the the 2D Context spec for cloning, the way the  
> Vocabulary
> spec for <iframe> has to defer to the Core spec for Window and  
> browsing
> contexts and the way the Core spec has to defer back to the Vocabulary
> spec for the parsing, the way the Communications spec adds things to
> Window and the way communicating between Window objects in the Core  
> spec
> that are kept in <iframe>s in the Vocabulary spec needs the  
> postMessage
> API in the Communications spec...
>
> IMHO this is a terrible way to organise the spec, it would be much  
> better
> as a single document exactly as the WHATWG has it:
>
>   http://www.whatwg.org/specs/web-apps/current-work/
>
> (In fact it would be even better IMHO if we could merge back in things
> like the Web Storage, Web Sockets API and Protocol, Workers, and
> Server-sent Events specs back into one "Web platform" spec, like this:
>
>   http://www.whatwg.org/specs/web-apps/current-work/complete.html
>
> I'd even argue that we should go as far as adding in XHR2, CORS, and  
> other
> "core" Web specs, though I haven't set that up yet. The idea that  
> the Web
> platform should have dozens of specs is not one that makes much  
> sense to me.)

The Web platform should not be one giant spec for the same reason an  
operating system should not be linked into one giant binary that's  
compiled from a single giant source file. The bigger it gets, the more  
it strains human comprehension. Likewise you wouldn't want an  
operating system split into a separate binary for each line of code,  
because then the complexity of cross-linkage would strain human  
comprehension. Good software architecture consists, to a large extent,  
of making pieces that are the right granularity, even in the face of  
complex relationships and leaky abstractions.

In my role as an implementor, I often find myself needing to read a  
spec, for a number of reasons. Sometimes I am implementing a new  
feature, other times I'm dealing with a bug report and I want to know  
what the standard behavior is, and still other times (and perhaps  
these are the most important), I am reviewing someone else's patch to  
add a new standards feature or fix a standards bug. I've found that  
when something is defined in a relatively small spec, it tends to be  
much easier to get correct understanding, even when there are  
significant external references. Features defined in a very large  
spec, like SVG 1.2 Tiny or HTML5, tend to be harder to grasp. I've  
found this is true not only for myself but for contributors providing  
patches as well. It seems more common to misunderstand things in large  
specs because there are so many basic concepts you need. Now, it's  
true that a rat's nest of cross-references can also make things hard  
to follow, but I've less often run into active implementor confusion  
as a result. In particular, even though XHR2 depends on CORS and HTML5  
in a detailed way, the fact that the three are separate specs has not  
been an obstacle to understanding in practice.

Thus, I think making HTML5 significantly bigger than it is already  
would strain the comprehension of implementors, and thus lose a lot of  
the benefit we're getting for the precise, detailed requirements in  
HTML5. HTML5 makes it much easier to converge on interoperable  
behavior through its exacting precision, but if implementors are not  
able to follow it, then it won't end up having that benefit. And I  
think ease of understanding for implementors is a more important  
consideration than theoretical purity or convenience of editors.

Having read over the spec splits some more, I tend to agree with  
Jonas's opinion. 2DContext, Communications and Microdata seem like  
reasonable spec units. They have significant cross-references, but not  
to the point that it erases any benefit of modularity. They seem to be  
drawing plausible boudaries, even if they are leaky at the edges. One  
way to see this is that the internal cross-references greatly exceed  
the external ones. The Core and Vocabulary specs, on the other hand,  
do not draw a clean boundary and are majorly entangled with each  
other, as currently drafted. I say this despite, like Jonas, feeling  
that Window, History, browsing contexts and the like should in  
principle be factored out.

I would personally be happier with the spec boundaries if the  
Introduction, Core and Vocabulary drafts were recombined. I do think  
there is a sensible Web Platform Core split that could be done, but I  
don't think this is it and I don't think we'll have one ready in time.

I'm interested in hearing input from others on this topic as well.

Regards,
Maciej

Received on Saturday, 9 January 2010 02:28:49 UTC