Re: New split-out drafts

On Fri, Jan 8, 2010 at 6:28 PM, Maciej Stachowiak <mjs@apple.com> wrote:
>
> 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.

To make it perfectly clear, I agree with all of the above. Including
the implementor experience.

/ Jonas

Received on Saturday, 9 January 2010 03:24:39 UTC