Re: New split-out drafts

Quoting Jonas Sicking <jonas@sicking.cc>:

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

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

[...]

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

My experience is that having a single spec is rather helpful; I  
typically look things up in the single page version of the spec since  
this makes searching and cross-referencing easier. I find the  
organization of the spec into chapters to provide sufficient  
granularity of concepts and, in cases where I am clear what I am  
looking for, I can look at the relevant chapter in the multipage  
version of the spec so as not to incur the overhead of loading the  
whole document. I have also observed situations in which people have  
misunderstood specs split out from HTML5 because they have failed to  
follow the cross-references when necessary.

It seems to me that, neglecting primarily political concerns, a  
monolithic spec that is well structured and available in both  
single-page and multi-page versions is rather similar to a spec that  
is split into many different documents except in the latter case it is  
harder to get a single document containing all the material one might  
need to understand the HTML/DOM part of the web stack and it is harder  
to find the right material if one doesn't already know where it lives.

Received on Saturday, 9 January 2010 23:39:37 UTC