API elements that are not implemented anywhere

[hamishwillee]

If an API entity such as an interface or a method/property in an interface is not implemented in any of our main user-agents (i.e. the things in browser-compat-data), MDN policy is that we should not document them.

Recently I deleted ::cue-region from the WebVTT API for this reason. The reviewer suggested that they are now leaving notes about these kinds of APIs to make it clear to authors and readers that this is a deliberate omission. For that reason I added the comment:

I think our current policy of not documenting makes a lot of sense - particularly for readers, who we don't want to be going to the specs to find out things - and who should therefore not even know ::cue-region exists.

But if this is something that is creeping in, then we should have an agreed and consistent policy on this - ideally something that can be auto-populated from IDL and BCD.

Thoughts?

[Josh-Cena]

Average readers may not be reading the spec, but as long as 1 out of 100 readers reads the spec, and 1 out of 100 spec readers forget to check implementation status (or not know this inclusion policy), we would eventually receive an issue saying "hey you missed this"—that's how our content issue log builds up. It's better to preempt these kinds of issues by just saying "hey we don't forget, but we intentionally don't document it".

[bsmth]

I've seen some of this usage recently when removing values for CSS props, for instance, to include a note in prose. If you do a search for not implemented there are a few places dotted around: https://github.com/mdn/content/pull/31137/files#diff-685b63e39a2f4c5bcad6f8a987695bbf82f45db82cfa2cd2666d69dbb6cd311bR54

The pro of it being in prose is that it's reader-visible and stops issues being raised. The downside is that it's harder to track in a stable way.

Comments are great in the sense that they can have any format, and one we can string match, but they're not reader-visible.

Shall we consider a template string for this or even an admonition? A Note block with a string ("Not implemented")?

> **Note:** **(not implemented)**
>
> The `Window: clipboardchange` event is specified in Y but has not been implemented by any browser.

[rachelandrew]

I've always been of the opinion (and this has come up multiple times over the years I've been involved with MDN) that where there is a mostly implemented spec, with a few unimplemented features, it would be better to have a stub page for the unimplemented features that explained no browser implements the feature, and when one does the page will be filled out at that point.

That way it's clear for the few who do read the spec, and the lack of support clarified. Otherwise we're using absence of a page to infer lack of support, when we have many features that are supported yet undocumented. It's therefore impossible to know if lack of a page means the docs just haven't been written or the feature is not implemented.

[hamishwillee]

@rachelandrew @bsmth What I like about the stub idea or the note idea is that they are a canonical statement - there is no guessing about what is supported or not supported - particularly in cases where most things are implemented and so you might well wonder about the others.

The problem is that it's either of these are only "true statements" at time of writing, and it is historically hard for us to keep in sync with current state of play. With Web APIs (at least) I think the Onkar Automation™ has done wonders for accuracy so perhaps we could use a similar approach here?

So instead of a stub or a note, we have a parser that runs across the API overviews (or corresponding CSS/JS docs), and if there is an IDL entry on a supported API that does not have a corresponding BCD entry then we get automatic addition of the API entity name in the API Overview view, with an icon to indicate that there is no indication of support - essentially something that indicates "not in BCD".

• If there is no API overview or other top level entry then nothing happens - we don't document the fully unsupported APIs
• If the API becomes supported we get new icons, and at least at the top level it becomes clear than the thing is not unsupported.

The most important thing is that we're all using the same approach.