Re: Reference to the HTML specification

On Sun, 4 Sep 2011, Doug Schepers wrote:
> On 9/3/11 2:54 PM, Ian Hickson wrote:
> > On Mon, 29 Aug 2011, Philippe Le Hegaret wrote:
> > > 
> > > But, the WHATWG HTML links to the editor's drafts and does not link 
> > > to the TR one. While documents on the REC-track should link to other 
> > > documents on the REC tracks, this doesn't apply to editor's draft, 
> > > which have no special status anyway. So, you can link to both 
> > > versions in the editor's draft if you prefer.
> > 
> > Well, the editor's drafts have one special status: they're the most 
> > correct drafts, unlike the TR/ drafts, which are often obsolete as 
> > soon as they're published (in the case of the HTML spec, they're 
> > obsolete _before_ they're published, since the publication process 
> > takes several days). So it's not entirely true that they have no 
> > special status.
> 
> Let's examine that claim objectively.  Specs define two different 
> flavors of behavior: documentation of existing features, and new 
> features.  (Sometimes one spec, like HTML5, does both.)
> 
> 1) Documenting existing behavior:  Here, the specification is attempting 
> to define a feature that matches one or more existing implementations 
> which are believed to be stable and to have the generally desired 
> behavior.  In this case, if the editor's draft in fact matches the 
> behavior, the specification is "correct"; however, to determine if the 
> spec achieves its goal, you need adequate test cases and implementation 
> reports to make sure that all the details are indeed correct.

The same applies to the TR/ drafts. The TR/ drafts are just older copies 
of the editors' drafts. By definition, if the TR/ spec at time /t/ is 
"correct", then the editors' draft was "correct" at an earlier time less 
than /t/.

Naturally, you need tests (though not reports, that's just bureaucracy). 
But the tests are needed to write the spec in the first place. No 
competent editor writes specs documenting existing behaviour in a vacuum 
without checking what that behaviour is.

So this point doesn't affect my point about how the TR/ page is just an 
out of date version of the editors' drafts, and that therefore the 
editors' drafts are "special" in the one sense of being more up to date.


> 2) Defining new behavior:  Here, the specification is trying to satisfy 
> a set of use cases and requirements that may not yet have a clear 
> solution.  This needs not only tests, but the consensus of the group.

No, it doesn't need consensus of the group. It merely needs buy-in from 
some specific engineers who will impact whether or not the relevant user 
agents will implement the spec.


> Of course the editor believes it's correct... they wouldn't have 
> specified it that way if they didn't.

Were that only so. Only the most immodest and inexperienced of spec 
writers would expect their first proposals to be correct.


> But sometimes editors have made a technical mistake, or informed 
> opinions vary on what the desired behavior is.  This is especially 
> unstable, because there is no reference implementation that needs to be 
> matched for backwards compatibility and interoperability, and there may 
> need to be a period of experimentation (in the spec drafts, or in 
> implementations) before a good solution is ready.

Indeed. But this doesn't affect my point. The TR/ page is equally unstable 
on this front, until such time as there are implementations, at which time 
the spec (again by definition) switches from this second "flavour" to the 
first (since now there are implementations to describe).

In fact the TR/ page is worse than unstable -- it also is out of date, 
being merely old copies of the editors' draft, not reflecting the latest 
fixes for the technical mistakes, and the latest corrections based on 
information discovered during implementation, etc.


> It makes sense that you, as an editor, and as someone who wants to 
> perpetuate the notion that specs are never stable

I don't want to perpetuate that notion any more than I want to perpetuate 
the notion that gravity attracts masses or that water at room temperature 
is a liquid. It's just a fact of life that specifications that describe an 
evolving ecosystem cannot be frozen in time.

Anything that attempts to describe something that changes over time itself 
must change over time if it is to remain accurate.


> should want to give special status to your own work, but to claim that 
> editor's drafts are "correct" is a gross oversimplification.

Yes, it's a gross oversimplification of what I said. As is Philippe 
claiming that editors' drafts have no special status.

I merely claimed that the editors' drafts are the _most_ correct.

This shouldn't even be controversial.

Consider the evolution of a spec. Here is the spec's trunk, with revisions 
being made on a regular basis -- the horizontal axis here is time:

  r16 n17 r18 r19 r20 r21 r22 r23 r24 r25 r26 r27 r28 r29 r30 r31
 --|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|--
                                                           ---------> t

Now some of these are published on the TR/ page. It takes time to publish 
the drafts, and the editors' draft continues to be updated as this happens:

  r16 n17 r18 r19 r20 r21 r22 r23 r24 r25 r26 r27 r28 r29 r30 r31
 --|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|--
           \                           \
            `--------| WD3              `-------| WD4
                                                           ---------> t

If we assume three changes are made to the editors' draft during the 
publication of the TR/ page snapshot, then even if a whole one third of 
the edits made to the spec actually make the spec _worse_, then on average 
the trunk is _still_ going to be more correct than the TR/ page when the 
TR/ page update comes out -- and it will continue getting more and more 
correct even as the TR/ page doesn't change.


> Instead, a more credible claim should be that editor's drafts reflect 
> the most recent best attempt by the editor.  That's not always stable, 
> and it's not always right.

The TR/ page isn't always stable, and isn't always right. Indeed, the TR/ 
page just represents the best attempt by the editor at an earlier time -- 
if there are editors who are doing such a bad job that their best attempt 
in the past is better than the best attempt in the present, then they 
should stop editing specs! But such a trend would imply that the next TR/ 
draft is going to be even worse as well, so if we follow that argument to 
its logical conclusion, the most correct draft is neither the latest TR/ 
snapshot nor the latest editors' draft, but the blank page that the editor 
started with.

Look at the chart above again. Consider the time when the WG decides that 
r25 should be annointed WD4. If WD4 is better than WD3, then that means 
that before WD4 is published, the editors' draft *is better than the 
current TR/ page spec* (in this case WD3). So even if you think every 
other revision is worse somehow and the editor made a heroic effort in r25 
to suddenly bring the spec to be better than r18, there is still a time at 
which the editors' draft is in one sense special, which was my point. 
(Special in this case because it's the most correct.)


> I believe that we should, in general, defer to the editor, because they 
> have delved most deeply into the subject matter and are probably best 
> informed about the issues (Aryeh wrote a nice essay on this recently). 
> However, sometimes a little distance from the subject is also useful, 
> because the editor might be too immersed in it to be able to see the 
> perspective of the people who will ultimately use the feature.  And in 
> any case, if the editor really does know best, they should easily be 
> able to describe and justify the feature to the rest of the group.

That doesn't seem to have any bearing on my point, but maybe you weren't 
arguing against my point here. I'm not sure.


> I also support the idea of a prominent warning to reviewers or 
> implementers that a more recent draft is available, and that they should 
> refer to that before spending too much energy on the TR draft; I see no 
> harm there, and potential a lot of benefit.  But equally, the editor's 
> draft should bear the warning that it may not have undergone substantial 
> independent review.

The TR/ drafts have undergone exactly as much independent review as the 
editors' drafts from which they are made (obviously). Furthermore, the 
review that editors' drafts and TR/ page drafts get are what inform the 
changes to the editors' drafts -- so not only have the editors' drafts had 
just as much review, they've also had the fixes resulting from that 
review. Review is not very useful if we ignore the feedback. Just look at 
HTML4. It's had lots of independent review. What good does that do us? 
Even the errata hasn't been updated in six years.


Anyway, my point was just that Philippe's statement that an "editor's 
draft" has "no special status" is false, and I stand by this: editors' 
drafts are the most up-to-date revisions of their respective specs. Since 
TR/ drafts are snapshots of editors' drafts, it would be impossible for a 
spec on the TR/ page to be more up-to-date than the latest editors' spec. 
At most, it would be _as_ up to date, and that only if the editors stopped 
work after the TR/ page copy is forked.

-- 
Ian Hickson               U+1047E                )\._.,--....,'``.    fL
http://ln.hixie.ch/       U+263A                /,   _.. \   _\  ;`._ ,.
Things that are impossible just take longer.   `._.-(,_..'--(,_..'`-.;.'

Received on Monday, 5 September 2011 03:55:32 UTC