OWD project: Generate "experimental" banners from BCD

wbamberg commented 2 years ago

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. https://github.com/mdn/content/pull/9941, https://github.com/mdn/content/pull/11741, https://github.com/mdn/content/pull/10220, https://github.com/mdn/content/pull/10706, https://github.com/mdn/content/pull/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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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.

jensimmons commented 2 years ago

I would love to see this. I would also recommend thinking carefully about the wording of the banner, so it conveys something that means "hey, this isn't in every browser yet, you should think through what to do and use progressive enhancement" instead of "this is dangerous, it's too early to think about using this technology, you should wait until it ships in all browsers".

OnkarRuikar commented 2 years ago

At the moment we are using a temporary solution to automatically update the banners and inline badges as per the latest BCD. A script runs automatically after every BCD release and updates the docs. The script is not part of the yari; once stable it may become part of the mdn/content automation. This is not ideal but it has been keeping the things up to date.

I would also recommend thinking carefully about the wording of the banner

Feel free to create pull requests: https://github.com/mdn/content/edit/main/files/en-us/mdn/writing_guidelines/experimental_deprecated_obsolete/index.md https://github.com/mdn/yari/edit/main/kumascript/macros/SeeCompatTable.ejs

"hey, this isn't in every browser yet..."

Even if every browser has the feature, but if it's behind flags or prefixes (e.g. -webkit-) then it is treated as experimental. [ref]

Also there is a caveat, if only one browser has been supporting the feature by default for more than two years then it's not experimental. Concerns about this can be found here.

Elchi3 commented 10 months ago

Thanks to @OnkarRuikar this is mostly automated now (even though it's not part of Yari).

I'm not sure how much of a future the "Experimental" banner really has, though. The new banner at the top of pages is the "Baseline" banner. And it seems that the "Experimental" banners will go away in favor of the "Baseline" banners. Currently they are both appearing: https://developer.mozilla.org/en-US/docs/Web/API/Background_Fetch_API but I believe the plan would be to retire the "Experimental" banner, c.f. https://mastodon.social/@pepelsbey/111594537123169125.

More feedback, especially on the wording on any of the banners, should be filed with in Mozilla's Yari repo.

In BCD, we're looking into automatically setting "experimental" at build time: https://github.com/mdn/browser-compat-data/pull/21860. That means that even in BCD no one will have to maintain it manually. Yay even less contribution friction! I guess BCD will keep the automatically generated "experimental" status for now (or as long as consumers are interested in this flag, seems like MDN might not be interested in it anymore in the mid-term as "Baseline" replaces it).

All this said, I don't think it is a good use of our time to work on this project anymore. Thanks to @OnkarRuikar and to @wbamberg for all of your thoughts and work on it in the past.

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.

Yes, I think these other things might still valuable for us to look into. I'd encourage you to think about them and file a new OWD project proposal.

openwebdocs / project