Consider linking to latest published versions instead of Editor's Drafts

[strugee]

I was just reading about rel="preload" on MDN and wanted to consult the specification. The specification table stated that the spec was in CR, so imagine my surprise when I clicked the link and suddenly landed on an Editor's Draft page, complete with large scary warnings that the specification might radically change out from under implementors.

This seems unideal. If a published CR or PR is available it seems like that's what most people on MDN would want to be consulting. If they really want the Editor's Draft they can still click the link to it in the spec header.

[roastchicken]

I just noticed this with the File API, because the specification table shows a Working Draft but links to the Editor's Draft. Maybe W3C used to update the GitHub repositories with the latest published versions? Regardless, now it seems they only host Editor's Drafts.

I agree with @strugee that the links should go to the latest published version. There are currently 75 links to wc3.github.io in the SpecData file, and I imagine most of these are specified as something other than an Editor's Draft. I think the suggested change could be accomplished by simply replacing w3c.github.io with www.w3.org/TR in all the links, and then checking through to revert any actual Editor's Drafts ("status": "ED").

[roastchicken]

@chrisdavidmills you seem to be one of the most active maintainers so I'll ask you.

Does this sound like a good idea? I'd be happy to create the pull request, but I'd like to make sure this is something you guys are actually interested in having changed before putting in the time.

[sideshowbarker]

Maybe the biggest reason it’s a bad idea for MDN to link to drafts published under www.w3.org/TR instead of w3c.github.io drafts is that browser-engine implementors always work from w3c.github.io drafts instead of www.w3.org/TR drafts.

For that reason, anyone editing content at MDN should also be working from w3c.github.io drafts instead of w3c.github.io drafts.

Given that, providing MDN readers with spec links to www.w3.org/TR drafts would mean we’d be pointing them at spec versions that neither browser-engine implementors nor MDN editors are using.

The reason browser-engine implementors don’t work from drafts published under www.w3.org/TR (and the reason MDN editors shouldn’t either) is that many drafts under www.w3.org/TR are obsolete — and for a spec that’s still being very actively edited, many www.w3.org/TR drafts basically become obsolete as soon as they’re published there.

Specifically — and especially in the case of actively-edited spec — www.w3.org/TR drafts may lack important/essential changes to the spec source which the editor has made since the time when the www.w3.org/TR draft was published; so the www.w3.org/TR draft may not have critical spec-bug fixes, API changes, important editorial clarifications, and so on that are in the w3c.github.io drafts.

[andreastt]

/TR drafts does typically not reflect the current reality of web browser implementations. If we want MDN to reflect reality—and I suspect we do!—we should link to the documents that most closely describes browser’s current behaviours.

Specifications get published under /TR for widely different reasons. Some working groups define a goal (i.e. a set of features to define), some publish when the specification text reaches some level of stability or gains adoption, yet others publish snapshots completely arbitrarily (i.e. according to a fixed schedule).

Regardless the process, what they have in common is that bugs are found, improvements are made, and new features keep getting added. When a web author wants to know exactly how a PresentationRequest works under the covers, the most recently revised definition is likely to be the most accurate and in touch with reality.

For a browser engine developer working on implementing web platform APIs, this is the only thing that matters: specification text is developed in tandem with browser engines, often fixing inconsistencies in the specifications as new implementation details are reviewed.

Fortunately most working groups (honourary hat tip to CSS) are quite good at rapid promotion of Editor’s Drafts to Working Drafts, limiting the damage done by anyone referring to /TR. But one random example of the contrary is https://www.w3.org/TR/webdriver1/, published 5 June 2018. If you compare it to https://w3c.github.io/webdriver/ there are substantial differences that makes the living document more pleasant to read, but also of bugs and changes to semantics.

[roastchicken]

I know very little about the W3C Specification process, so I'll trust @sideshowbarker and @andreastt in their statements that the most useful version to link to is the Editor's Draft.

Assuming this is the direction MDN wants to go, how should it be reconciled with the specification "Status" listed next to the specification link on MDN pages? Most of the links to editor's drafts (w3c.github.io) are not marked as "Editor's Draft" in the status, but rather the status of the latest published version. Is this what we want? To link to the Editor's Draft but show the status as something else in the Specification Table confuses me, personally.

[domenic]

For a long time I've hoped MDN would completely removed links to outdated specs, and only link to editor's drafts/living standards/etc. Then the status field could disappear entirely. That seems like a really nice way to resolve this confusion while at the same time improving the discovery path for readers and the internal consistency of MDN itself.

[jpmedley]

Right now we have the absurd situation that Web Authentication is a candidate recommendation yet is only implemented in 2 browsers while service workers, which have a very broad support (not to mention cross-browser consistency), is still only a working draft. So what is the value of listing a spec's formal status?

If status is to be kept at all, then a fundamental problem with the specifications section needs to be fixed: namely, that it implies that if I click the specification link that I'm going to get the version for the listed status. I've always thought it was confusing that it doesn't. This is not an argument for or against linking to the /TR version. This is an argument for finding a better way to present the information.

[Elchi3]

I would be in favor of dropping the spec status information from MDN reference pages and just link to the most relevant spec that talks about implementation reality.

I'm responsible for MDN's ECMAScript docs and I'm pleased that @sideshowbarker has worked on https://github.com/mdn/browser-compat-data/pull/2983 where we (with agreement from TC39 representatives) have added relevant spec_urls to the BCD data set. I'm planning to use this as the source of truth and I will remove links to all other ECMAScript specs. I hope we can work towards something similar in other MDN Web doc areas.

[chrisdavidmills]

I (as manager of MDN content) also agree with this, after some thought. I don't really know who that information is really useful for. Certainly not the average web developer who reads MDN. And it is confusing.

So should we just:

• get rid of the status column
• get rid of older specs that aren't needed
• add an explanation/info button explaining that the specs listed are the latest editors drafts because these are what browsers tend to implement things off of, so therefore reflect reality.

?

We could do this as pat of the maintenance work we are planning for this year.

[strugee]

• add an explanation/info button explaining that the specs listed are the latest editors drafts because these are what browsers tend to implement things off of, so therefore reflect reality.

Late to the party (in my own issue, whoops) but if we wanted to go this route we could just rename "Latest published version" to "Implemented by browsers" - no need to add a separate explanation, it seems to me.

[chrisdavidmills]

I've actually been working on a wider plan that covers this and other issues about the MDN spec tables — see https://docs.google.com/document/d/1eL8YtslVZAnIAGb7rcZGbvXndkcR7lb9rhDpvGpGaWs/edit?ts=5c6ea9bf#heading=h.xvn365mcy2pj.

[a2sheppy]

I agree that we should just link to the working copy on Github for the specs and be done with it. There's no point in linking to a bunch of out of date specs, and it's true that everyone really works off the working copy nowaways anyway.