OWD project: use webref as the source for CSS formal syntax, instead of mdn/data

[wbamberg]

This proposes that we should start using the w3c's webref project as the source of CSS formal syntax, instead of mdn/data.

Problem statement

In our CSS documentation we have a section "Formal syntax". This is built using a KS macro CSSSyntax, which gets the data from the mdn/data repo.

The specifications are the source of truth for this data, so it's not optimal having this separate copy in mdn/data. Sometimes the version in mdn/data falls behind and we have to remember to update it, or people get outdated information.

It turns out that the w3c already makes this information available in a machine-readable way in their webref project. So this issue proposes that we:

• start using webref as the source for this, rather than mdn/data
• stop maintaining the formal syntax in mdn/data.

Priority assessment

This table checks this project against the OWD prioritization criteria.

Criteria	Assessment
Effort	Small. We'd need to update the CSSSyntax to fetch the data from webref rather than mdn/data. It's a complex macro but I hope we can leave most of the complexity untouched.
Dependencies	Depends on dev team for review of changes to the KS macro and to bless a new dependency in Yari. Also depends on any key users of mdn/data (most obviously CSS Tree) being informed and helped to move away from mdn/data.
Community enablement	Low (though helps us build more things with the w3c).
Momentum	None.
Enabling learners	No. CSS formal syntax is pretty much a power-user thing.
Enabling professionals	Would help ensure professionals get up-to-date formal syntax in MDN pages.
Underrepresented topics / ethical web	N/A
Operational necessities	N/A
Addressing needs of the Web industry	N/A

Task list

1. Understand the interface of webref and how it maps to mdn/data, and whether there is anything missing that we would need.
2. Get agreement from the dev team to add webref as a Yari dependency.
3. Get agreement from key users of mdn/data to migrate away from it, towards webref probably.
4. Update Yari dependencies to include webref.
5. Update CSSsyntax to use webref instead of mdn/data.

Additional comments

There's a bigger version of this proposal in which we replace not just the formal syntax, but all the CSS data in mdn/data, with webref, and may then be in a position to retire mdn/data entirely. But this is a major step towards that goal, has value in itself and keeps the project small. If, when we get into it, replacing the other CSS data seems straightforward we could consider doing that in this project as well.

[teoli2003]

Would this project cover the generation/replacement of https://github.com/mdn/yari/blob/main/kumascript/macros/InterfaceData.json ?

I think all the info in it could be generated by one of the package offered by w3c/webref.

(Technically it is not in mdn/data, but it looks like a fairly contained project to experiment with w3c/webref)

[wbamberg]

I'm not sure this project would - it's intentionally quite a narrow scope - but definitely making more use of webref generally would be worth looking into, to replace various data sources that we sometimes struggle to maintain.

[wbamberg]

@dontcallmedom , I filed mdn/yari#4656 the other day, which replaces mdn/data with webref as a source for formal syntax.

[wbamberg]

I'd like to add that we have a draft PR that implements this proposal at mdn/yari#4656.

It not only uses webref, but also reimplements the macro to use https://www.npmjs.com/package/css-tree to parse the syntax, as a result of which it's able to add pretty-printing and syntax highlighting to the rendered syntax, making it much more readable.

[wbamberg]

Oh, this is done :)