Add data guidelines for spec URLs to the docs/data-guidelines.md project documentation

[sideshowbarker]

Some best practices have emerged from the work on adding spec URLs to BCD. We should formally document those in the docs/data-guidelines.md project documentation. Some are described in the issue description at https://github.com/mdn/browser-compat-data/issues/10090#issue-867900827 — but those are specifically for URLs from the HTML spec. So there’s more ground that would need to be covered.

---

From https://github.com/mdn/browser-compat-data/issues/11216:

• What version of the spec should I use?
• If a feature is plausibly represented in more than one spec, which one do I use or do I use both? When do I use more than one spec_url?
• What's the preferred fragment target?
• When a spec isn't represented in w3c/browser-specs, what qualifies a spec for inclusion in our exceptions list?

[Elchi3]

One thing to talk about here is definitely the role of the https://github.com/w3c/browser-specs repo which works well as an allowlist for spec host URLs. It should be mentioned in the guidelines that relevant specs are defined by this project.

(Daniel and I also talked about making a linter for BCD that checks if spec_urls only use the spec hosts defined by w3c/browser-specs but linting is a separate issue)

[sideshowbarker]

Today I came across as very good example of why it’s important to have BCD link to developer-specific spec anchors.

https://github.com/mdn/content/issues/4342 is issue raised to propose changing the language of the Return value part of the Syntax section at https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/whenDefined#syntax.

I notice that article has https://html.spec.whatwg.org/multipage/custom-elements.html#dom-customelementregistry-whendefined as the link in its Specification table. That spec link takes the reader to algorithm that defines the steps a browser must perform when the whenDefined() method is invoked.

So a web developer following that link would not find any language clearly describing the return value.

But the thing is, at https://html.spec.whatwg.org/multipage/custom-elements.html#dom-customelementregistry-whendefined-dev there is language written for developers which clearly describes the return value — in fact, the Return value part of the Syntax section of that MDN article has the same language as that part of the spec, pretty much verbatim.

My point is that if the MDN article has linked to that developer-specific part of the spec, the person who raised https://github.com/mdn/content/issues/4342 would have have seen that the language in the MDN article came verbatim from the spec.

So to generalize from this, it seems like we have clear evidence that linking to developer parts of specs can save developers a lot of time and confusion. I think we know that intuitively already — but it helps to have real-world evidence like this.

[gsnedders]

A case I came across right now is Error.stack, where we have no spec_url, but the content page says:

Note: The stack property is de facto implemented by all major JavaScript engines, and the JavaScript standards committee is looking to standardize it. You cannot rely on the precise content of the stack string due to implementation inconsistencies, but you can generally assume it exists and use it for debugging purposes.

On the one hand, it is a TC-39 Stage 1 draft.

On the other hand, it is something in way of a spec.