OWD project: Generate "experimental" banners from BCD

[wbamberg]

Currently we store information about whether a feature is experimental in two different places:

• in the page itself, as a call to the {{SeeCompatTable}} macro, which adds a banner to the page
• in BCD, as a status flag

We do a pretty good job of maintaining the BCD version, much less well of the version in the page, so they often get out of sync and we get people asking why we are warning people about perfectly good APIs (see e.g. mdn/content#9941, mdn/content#11741, mdn/content#10220, mdn/content#10706, mdn/content#12506, etc etc).

We should display "experimental" banners based on the data in BCD, just as we now display spec tables based on BCD data.

What's involved?

• updating Yari so it displays an "experimental" banner based on BCD
• for pages that don't have BCD (mostly, API overview pages), add front matter to represent experimentalness
• remove the {{SeeCompatTable}} macro

What's the benefit?

Immediate benefits

• more reliable pages
• easier to contribute and maintain MDN, as there's only one place to maintain this

Long-term/strategic benefits

This is in line with our general desire to build MDN content from data, where that's appropriate. We should implement this with an eye to doing something similar for other MDN banners, like "deprecated", "available in workers", "requires a secure context", "requires permissions" etc. All these things should be amenable to maintaining as data and rendering in Yari, rather than being part of unstructured prose content.

Prioritization criteria

Effort

Medium. Need to:

• update Yari to add the banners based on BCD (small)
• update ~960 pages that currently use SeeCompatTable (small)
• design and implement a solution for pages that don't have BCD (small-medium)

Dependencies

Needs a little Yari work.

Community enablement

Make it easier to write MDN docs by only having one place to add the data.

Momentum

n/a

Enabling learners

More reliable docs benefit all users.

Enabling professionals

More reliable docs benefit all users.

Underrepresented topics / ethical web

n/a

Operational necessities

n/a

Addressing needs of the Web industry

n/a

[OnkarRuikar]

What about inline badges? {{Deprecated_Inline}}, {{Experimental_Inline}}, and {{non-standard_inline}}. e.g. https://developer.mozilla.org/en-US/docs/Web/API/Window They also need manual updates.

Can we have a macro that we can put in front of all props and method listings? Like:

- vrdisplayactivate {{InlineBadges{'window.vrdisplayactivate', 'readonly')}}

Which will yield following based on BCD:

• vrdisplayactivate 🗑⚠🧪

Second onwards parameters could be extra badges, like readonly, that we may add in future. This will also put badges in same order everywhere. Right now there is no particular order in which the inline badges are displayed.

---

The deprecated etc. info is also stored in page tags.

[wbamberg]

I wouldn't really want to have macros after every item, when almost always they have no output. So much visual noise in the source and extra typing.

In some far-off future it would be nice if we could generate these kinds of lists of methods - for example if we can represent as data the fact that an interface has a particular set of methods (which already exists in things like the IDL), then we could generate the method listing, and automate these badges, as well as things like consistent typography and alphabetization.

[wbamberg]

Or for a less sci-fi place to be, if:

• we have a page type such as, say, "web-api-interface" (like Request)
• and we know that pages of this type might include a section "Methods"
• and we know that "Methods" there is a <dl> where the <dt> elements are links

...then perhaps Yari could peek at the front matter for those linked pages, and add the badges automatically.