Notifying MDN about changes to specs

One thing I’ve discussed with a few people recently is more efficient ways to discover changes to web standards specs that result in documentation changes being needed.

At the moment, we most commonly discover such changes via the “dev-doc-needed” keyword being added to bugs on Mozilla’s bugzilla instance, but this is very Mozilla-centric, i.e. it only works when features are added to Gecko.

It has been argued that it would be more neutral and efficient to get this information directly from the spec teams, e.g. at W3C and WHATWG, with WHATWG probably being more relevant as this is often the first place new additions show up.

I talked to Anne van Kesteren about this, and he has already filed a github issue for WHATWG, which the team are happy to act on if we deem it a good enough idea to run with: https://github.com/whatwg/meta/issues/62

A label added to GitHub spec work relevant to the documentation would probably allow us to automatically populate our bug tracker directly from the GitHub source.

What are our thoughts on this?

1 Like

Hi!

There is a fundamental point to consider here. We document implementations, not specs. So a spec doesn’t lead to a change in our documentation, until a browser implement it.

WHATWG requires 2 implementations before accepting a spec, but I’m not sure if it is the same for changes. W3C and other bodies change specs before implementation. Spec changes should go to devs (of every browsers), not us. In other terms, WHATWG may be an exception here.

Ideally we would have a dev-doc-needed mechanism on EdgeHTML, Blink, and Webkit bug trackers, as well as on browser trackers that activate a feature. That way, we would have the information when things are implemented and not theoretical info years ahead of time, and on data that is unstable – it is rare that a spec doesn’t change significantly during the implementation phases of the lifecycle.

We should ask Joe and Erika about their workflow on discovering new features landing on Blink and EdgeHTML.

I agree that having a DDN mechanism on each browser’s issue tracking system would be helpful. However, I do feel that having a mechanism for monitoring changes to specifications that may be of interest is also helpful.

It’s also not entirely accurate to say we document implementations, not the specification. We actually historically (and officially, unless this has been changed very recently) document the specification, noting deviations from the spec for each browser. That’s what the browser compatibility section is for, after all – to note deviations from the spec along with the browser support details.

Sheppy

I think it would be useful to combine both approaches to some degree. If we used the spec system to get a wide net on breaking changes, it would then make sense to cross check that against browser bug trackers to see where the implementations are.

We could then handle it in the proposed content opportunity assessment — implemented features would obviously have higher priority than non-implemented.

It’s also helpful to be more easily able to detect when specs change because it gives us a chance to examine the changes and potentially notice problems that should be relayed back to the spec committee through a github issue or otherwise to hopefully avoid flaws or quirks in the spec from getting adopted before they can be fixed.

I think the MDN community is in a good position to potentially help prevent erroneous, contradictory, or poorly-defined specifications from advancing too far to be fixed.

Sheppy