OWD project: Up-to-date & machine readable specification links on MDN and in BCD

[Elchi3]

This is a write up of a project around specification links that @sideshowbarker and I started to work on and that I'd like to introduce here some more, so that it becomes more transparent why we should do some work on this and what work is involved exactly.

Problem statement

• The specification sections on MDN oftentimes present links to outdated or irrelevant specs. Browser engineers are unhappy to see links non-current specs and web developers get the wrong information about what is the latest standard. Some old specs are redirected by the W3C already, other links just continue to point to dated material or are 404.
• The spec links aren't machine readable like the compat data is. Various tools need a mapping between: mdn url, spec url and compat data.
• The MDN spec sections are inconsistent. If they were rendered from data, like the compat table, we could change the design of this section from a central place and iterate more on it.
• Currently, to add a spec to MDN, one has to add to the specdata kumascript macro in yari to first register a spec. Then it is possible to call a spec macro to display a link. This process is unnecessarily complicated and costs time.

Priority assessment

This table checks this project against the OWD prioritization criteria.

Criteria	Assessment
Effort	Large as this affects all MDN reference pages. However, thanks to the scraping work that Mike has done, we were able to quickly get spec_urls in for javascript and HTML pages already.
Dependencies	BCD and MDN are both involved. In order to render the spec section from a template like the yari compat table, we need yari engineering time. Collecting the spec_urls into BCD doesn't have a dependency, though.
Community enablement	Anyone can submit and review spec_urls to BCD features. Is shareable. Some knowledge about what makes a spec a current spec required.
Momentum	I think the momentum comes from being able to use this data in a machine-readable form in some spec tooling. No direct web developer momentum, I think.
Enabling learners	N / A
Enabling professionals	Professionals appreciate a precise spec section on MDN
Underrepresented topics / ethical web	N/A
Operational necessities	N / A
Addressing needs of the Web industry	N / A

Proposed solutions

• Add a spec_url property to BCD and review all spec_urls for correctness and if they point to the most recent spec version. (See Add spec_url values for all features for which we have the data mdn/browser-compat-data#6765)
• Source the MDN "Specification" section from the BCD spec_url. Source specification section from BCD; improve rendering mdn/content#1146
• Improve the rendering of the MDN "Specification" section.

Task list

• Define spec_url for BCD and agree on what sorts of specs qualify as correct and current.
• Populate spec_url for all BCD features (upstream from https://github.com/w3c/browser-compat-data but review data from there)
• Source the Specification section from BCD data
• Remove the specdata macro implementation
• (possibly more here)

[Elchi3]

Status update!

• Add a Specifications macro and extract a special specification section to the Document mdn/yari#3518 was merged and is deployed to MDN. This means we have a basic renderer for a BCD-powered Specification section.
• @sideshowbarker has been really busy and added many many spec_urls to BCD. We reckon we can get them all in sometime in May.
• JS docs have a BCD front matter now: Moved BCD query into front matter in JS docs mdn/content#4537 (this can now be used by both, the Browser compat section and the Specification section)
• Manual Specification tables have been removed from JS docs and now use the spec_urls from BCD Remove spec tables in JS docs, and replace with macro call mdn/content#4691
• https://github.com/w3c/browser-specs is the package that helps us with all of this. It provides the meta data for specifications and also provides the policies for what makes a spec a relevant spec.

[teoli2003]

@Elchi3 As it is a prerequesite for this issue, should I submit PRs for bringing BCD in front-matter all over the place? I have a Python script that does most of the work automatically; I only need to deal with special cases manually.

[Elchi3]

Yes, thanks for your work. BCD Front-matter is good for a variety of use cases.
In a next step, the specification section can then make use of it (via the new {{Specifications}} macro that is analog to {{Compat}})

[teoli2003]

Absolutely! We can script this change (spec table -> spec macro) too but two points must be checked:

1. If there are pages with a specification table but no BCD info, we need to check them and either add the corresponding entries in mdn/browser-compat-table or, if not relevant, to keep the table (or use a kind of {{Specifications("x.y.z")}} like with {{Compat}}). We can list these pages with a script and start handling them right away, I think.

2. If there are comments after the specification table, should we just keep them there or evaluate them on a case by case basis?

[Elchi3]

90% is done, the rest is blocked by other work. I'm not sure how much we want to rabbit whole into the remaining work in Q3.

Spec sections powered by BCD spec_urls are implemented for all major content areas on MDN.

• CSS
• HTML
• JavaScript
• HTTP
• APIs
• WebDriver
• MathML
• SVG (element pages)

The old spec tables still appear on:

• ARIA roles pages (not captured in BCD)
• API overview pages (example). Blocked by the general discussion on API overview pages: https://github.com/mdn/content/discussions/4920
• CSS overview pages (example). Same story as with API overview pages.
• HTML attribute pages. Blocked by the question if we should really have separate docs for HTML attributes Add spec_url to html attributes mdn/browser-compat-data#11240
• SVG attribute pages. Same here, dedicated SVG attribute pages make no sense oftentimes. Stalled PR: Use {{Specifications}} macro for svg/attribute/[a-f]* [DRAFT] mdn/content#5862
• A few random pages that use the old Spec2/SpecName macros.

[teoli2003]

Except for the "few random pages", I don't think we should invest in this in Q3, other than trying to move forward the discussions.

[Elchi3]

No disagreement in today's SC call to close this as done. 🎉
Follow-up projects can always be nominated and we will move open discussions forward as needed.

[teoli2003]

\o/