How to represent standards positions for experimental/non-standard features

[chrisdavidmills]

There have been discussions recently on how to represent standards positions for experimental/non-standard features.

@wbamberg wrote:

We describe when APIs are nonstandard, experimental, deprecated, or have varying support. Should we also capture standards positions, which effectively reflect whether particular browser engines intend to implement an API?

Example is the Topics API, for which both Safari and Firefox have registered "oppose" standards positions (WebKit/standards-positions#111 (comment), mozilla/standards-positions#622). So this is not just a Chromium-only API for now, but it is not likely to get multi-engine adoption in the near future. We should still document Topics on MDN, but perhaps we should also capture this nuance.

There are a couple of parts to this:

1. What it should look like when rendered.
2. How the data should be represented.

My discussion here will mainly focus on the first point. I intend that we should agree on and create a UI mockup in the Topics API docs to act as a test bed, then figure out how to better do this in a more automated fashion later on.

For the second point, we could look to have a front matter key to represent standards positions, or just put this info in the BCD. We'll need a macro update to render the data in the desired way.

There will also be a related discussion at some point soon around how to represent specs that aren't "real specs". In other words, specs that are unofficial or not in good standing in terms of cross-vendor standards positions.

When should we communicate standards positions?

I think we should communicate standards positions only when there is not a clear supporting consensus between vendors. The default should be no information communicated, which means that all vendors support the standard have either implemented it, or will be implementing it in the future.

How should we communicate standards positions?

In the Specifications sections, we should include a section along the following lines (the following uses the Topics API as an example):

### Standards positions

- Proposed by: Google (Chromium)
- Other vendor positions:
  - Mozilla (Firefox): (Negative)[https://mozilla.github.io/standards-positions/#topics]
  - Apple (Safari): (Negative)[https://webkit.org/standards-positions/#position-111]
 
See [Standards positions](LINK TO MDN EXPLAINER PAGE) for an explanation of what these mean.

I think we should just stick to three possible position types - Position, Neutral, or Negative. We will then link to the vendor's own position pages for more details.

We should create a standards positions explainer page that explains what all these details mean.

[wbamberg]

Thank you Chris!

Standards positions

• Proposed by: Google (Chromium)

Does it matter who proposed it? Is this always even clearly tied to a vendor?

• Other vendor positions:
• Mozilla (Firefox): (Negative)[https://mozilla.github.io/standards-positions/#topics]
• Apple (Safari): (Negative)[https://webkit.org/standards-positions/#position-111]

I think we should just stick to three possible position types - Position, Neutral, or Negative.

Does that imply that we also document "other vendor positions" when they are positive or neutral? In that case what does the "not a clear supporting consensus" rule above mean? I mean if, say, Mozilla is positive and Apple haven't responded, do we document that?

I think the main thing to communicate is when vendors have registered "oppose" positions, since that has the most relevance for developers, so perhaps we could only represent that? The default being that they are positive, neutral, or haven't considered it yet.

So I would prefer us to note only "oppose" positions. So if say we have the Foo API and Mozilla are opposed, Google are neutral, and Apple are positive, we could just say:

Specifications

(spec table)

• Mozilla are opposed to this specification

Alternatively we could just document all known standards positions, always. One problem then would be knowing when and if to remove these for specs that have been implemented. Do you know if Google has an equivalent of https://github.com/mozilla/standards-positions?

[chrisdavidmills]

Does it matter who proposed it? Is this always even clearly tied to a vendor?

I guess not.

Does that imply that we also document "other vendor positions" when they are positive or neutral? In that case what does the "not a clear supporting consensus" rule above mean? I mean if, say, Mozilla is positive and Apple haven't responded, do we document that?

I agree with you that it is more important to document situations when one or more vendors are clearly opposed to the spec in question and are therefore not likely ever to implement it. In which case my ruling paragraph should read more like:

"I think we should communicate standards positions only when one or more vendors are opposed to the spec in question and are therefore not likely ever to implement it. The default should be no information communicated, which means that all vendors support the standard, are neutral, or are undecided."

But I do think when one or more vendors are opposed, it would be useful to be clear on the positions of other vendors, where those positions exist. So for example:

## Specifications

(Spec table or link to unofficial "spec")

### Standards positions

One or more vendors oppose this specification. Known vendor positions are as follows:

- Mozilla (Firefox): (Oppose)[https://mozilla.github.io/standards-positions/#topics]
- Apple (Safari): (Oppose)[https://webkit.org/standards-positions/#position-111]

And would better language for the positions be:

• Positive, Neutral, Negative, Undecided
• Support, Neutral, Oppose, Undecided

?

I feel like the first one is possibly a bit more intuitive to non-English-first-language people. Maybe our European colleagues can provide their thoughts on that.

Do you know if Google has an equivalent of https://github.com/mozilla/standards-positions?

A quick search didn't bring anything up. @rachelandrew, do you think if anything like this exists for Google?

[rachelandrew]

Chrome/Chromium doesn't have an equivalent place.

[teoli2003]

Do we want to add a different text to the experimental banner when at least one engine has opposed a feature?

[chrisdavidmills]

Probably, yes. Something like

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production. Note that one or more browser vendors oppose this specification.

With "oppose" linked to the "Standards positions" heading.

Also add this to the Non-standard banner, if we still use that?

[estelle]

Experimental is known and oft-ignored as meaning "coming soon to a browser near you". A formal opposition from a vendor is different and should be presented differently, not as part of an experimental note.

Notes and experimental are both blue; very similar UI treatment, with just a flask icon added in the case of experimental. This must be at least at the level of a warning

[estelle]

We do not need to explicitly represent support. Support is explicit: it's conveyed by inclusion in a browser and on MDN. More so through BCD.
We 100% need to represent opposition 100% of the time.
"Experimental" is a blue flask.
"Deprecated" is a red trash can
Should we start with "Opposition" being a yellow warning triangle with a !? Or Red? Is a ! already used? Warnings also come with a skull and a nuclear tri-circle logo, but that likely is overkill.

If a browser is opposed, the spec will never have full support in BCD (or full baseline banner). We KNOW this will forever be the case. Therefore, all of the banners at the top should make the non-full browser compatibility abundantly clear.

• The baseline banner, if present, should be red (with an alternative !!! for those who have color vision deficiencies).
• The Experimental banner should not be included: it's not simply experimental, it's a no-go.
• A "Will never have cross browser support" banner must be added
• The warning can include links to the standards position statements, and a link to the standards position definition.

The link to the definition should be from the "i" or "?" as in more information. The term "standards position" is not a known one; use language people understand, rather than spec lingo, until the lingo is common parlance.

[chrisdavidmills]

Some good points here. I agree that the banner should be stronger than just "Experimental", although I'm not sure red/nuclear "no" is appropriate either. In an ideal world, developers just wouldn't use single vendor tech, but that is not the world we live in.

I think using a warning box would be appropriate. I found a warning box example. Maybe something like:

Warning: One or more browser vendors oppose this feature — in its current state, it will never be implemented across all browsers. See Standards positions and Browser compatibility for details of opposition and support status.

I'd see this replacing the experimental banner in such cases. I don't think the baseline banner is relevant in these cases. The "Standards positions" section would be the best place for a link to more information as to what this actually is, IMO. No need to clutter up the banner with this?

[estelle]

How about something like this:

Text:
Warning: This is an experimental technology
Check the Browser compatibility table carefully before using this in production. Some browser vendors oppose this specification, including Safari and Firefox.

[estelle]

I used the experimental heading, but changed the class to "warning", then added a sentence which could link to the standards statements. I envisioned the front matter being something like:

standards_position:
      https://github.com/WebKit/standards-positions/issues/111#issuecomment-1359609317
      https://github.com/mozilla/standards-positions/issues/622#issuecomment-1372979100

those seem parsable.

the specs opposed by webkit
The specs opposed by Mozilla (note that this is a seach for a label. Moz doesn't label all of their negatives; topics API does not have a label)

[chrisdavidmills]

I like this suggestion for the warning box.

I have proposed a similar but slightly different version in mdn/content#30654.

Specifically, see https://pr30654.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/Storage_Access_API/Related_website_sets for a preview.

[wbamberg]

I think this looks great. I've been wondering whether this ought to be a separate box or an addition to an existing one. I don't very much like the piles of boxes we get on some pages, and it does seem like that would happen here, as these APIs are also often experimental and nonstandard. However I guess it is possible for an API to be opposed by a vendor but still a standard, or still have multi-engine support? In which case it makes sense for this to be a separate box?

I mean all this is also an argument for a unified presentation of all these things instead of the "pile of boxes" model, but for the time being that's the model we have...

[Rumyra]

Thanks for opening the discussion @chrisdavidmills - I would love us to revisit our experimental/non-standard status'

I think this work is going to be (and can be) tied into the baseline work. We're already discussing a status which includes standards position. As for frontmatter inclusion - I would like to see this be even more data driven, I would like this info to be in the web features dataset.

[estelle]

We're already discussing a status which includes standards position.

Link to the discussion, please.

[Elchi3]

There is web-platform-dx/web-features#186 which talks about including a URL field in web-features. I'm not aware of other public discussions about data structures for standards positions. I'm happy to ask about this in the next WebDX calls, though.
However, I guess, for now, it is not that important how we store or get this data. I think this discussion is more about communication of standards positions in the docs and how we want to get that across to web developers best, also in combination with existing banners, etc. If there are views on that which could be shared, it would help this discussion and could feedback nicely into the UI design that is being created.

[Rumyra]

Can you share who is creating a UI design? And where - thnx

[Elchi3]

See the thoughts and screenshots above from various people? Do you have feedback on that?

[wbamberg]

The proposal by @chrisdavidmills described in https://github.com/orgs/mdn/discussions/463#discussioncomment-7715265 and implemented in mdn/content#30654 is now live: https://developer.mozilla.org/en-US/docs/Web/API/Storage_Access_API/Related_website_sets .

So the next step would be to document this in our page templates.

[Rumyra]

Please don't do this yet - I am opposed to this and would like to discuss it in our next community meeting - thanks

[teoli2003]

@Rumyra To make the next community meeting more efficient, can you elaborate on the reasons you don't like this proposal. That way, people can come on January 22nd with alternative solutions.

Otherwise, we will lose one extra month.

[Rumyra]

Thanks @teoli2003 - taking this out of thread:

Before I begin I would like to be clear I have very strong opinions about this and it is something I care about. However my thoughts this will go outside of the scope of this discussion, which I would still like to bring up as I feel it is important.

We describe when APIs are nonstandard, experimental, deprecated, or have varying support. Should we also capture standards positions, which effectively reflect whether particular browser engines intend to implement an API?

This is a great question to ask.

Point 1. By adding standards positions to docs what problem are we trying to solve - this isn’t clear within this thread, so if anyone can point me in the direction of where this was discussed previously that would be helpful, thank you.

Now, I’m not anti relaying this information to users, but I would really like to get some user research before we make decisions, as I believe we are making a number of assumptions, the main one being that this is useful. It could very well be, I do not argue that, but I want to see user feedback to prove our assumption. Maybe there was historically some research I am unaware of, again if anyone can point me in that direction I would be grateful.

Another thing I would like to see data for, so we again prove our assumptions:

Experimental is known and oft-ignored as meaning "coming soon to a browser near you". A formal opposition from a vendor is different and should be presented differently, not as part of an experimental note.

As I’ve already stated, I am happy to run short surveys. I think this requires one.

This is point 2, but related:

If a browser is opposed, the spec will never have full support in BCD (or full baseline banner).

The spec as it stands at the moment possibly will not be, but historically there have been a number of specs with opposing standards positions (sometimes for years), where spec groups and authors have come together and made amendments which then lead to cross browser implementation.

As said in the current text of the banner “in its current state, it will never be implemented across all browsers” However it took me a few reads to pick that apart. It’s comes across initially as there’s no point using this - I don’t think that’s something we on MDN have the right to determine.

Whether we agree with browser implementations of early specs or not is our own opinion. For spec writers to get feedback from developers, developers can only ascertain feedback by trying ‘experimental’ features. It is not for us to judge whether developers want to or not.

Point 3. Authorship of banners (in general)

I don't very much like the piles of boxes we get on some pages

Very strong agree. I envisage a world where MDN writers do not have to author banners at the top of our articles and there are much much less of them. Something that inspired baseline originally was that world, and I believe we are a lot closer than we give ourselves credit for.

I mean all this is also an argument for a unified presentation of all these things instead of the "pile of boxes" model, but for the time being that's the model we have…

“a unified presentation of all these things” something that has been proposed for a while. Yes baseline banners as they display on the website are in early stages, but discussions of standards positions/deprecated/experimental have been a part of those conversations since the beginning. This is something I feel strongly has a really good value addition to MDN, not just for our users but for maintenance cost and easier authorship as well.

If someone could explain the urgency of implementing this now, when there’s a strong possibility of us addressing this with research and web features work this year, then again I would be grateful.

Point 4. Maintenance costs

it is not that important how we store or get this data. I think this discussion is more about communication of standards positions in the docs and how we want to get that across to web developers best

I respectfully disagree. I’m so happy we have moved MDN on to have the capabilities to be more data driven. Architecture wise it makes a lot of sense, it reduces the complexity and burden on authors and I’m passionate about doing that. Removing cognitive overhead and complexity for us as writers, also fosters a more diverse community by reducing the friction to contribute (I reiterate passionate about this).

I think we now need to always consider how we store and get data. Authoring this information into pages feels a lot like adding browser compatibility to prose, which I’m sure we can all agree should be contained to bcd data.

There could very well be work needed to show data to users in a helpful and meaningful way, but until we start to considering technical architecture in decisions such as this, we will forever be chasing our tail.

Tl;dr: We seem to have jumped straight into ‘how this will look’ without giving consideration to a number of other variables.

[chrisdavidmills]

Thanks for writing up your feedback @Rumyra. There are some really useful thoughts here. I agree that it would be great to do some surveys and have some data to inform better what we do to solve this. I think that's the long-term goal.

I think the short-term goal is for us to decide on some wording for the banner that we are all happy with so that it can be put back up on the RWS landing page. I think it is important to have on there so that readers know what the deal is. This would be a short-term stopgap until we work out the final solution. I think that is OK because this is something that will only affect a few pages, not thousands.

To be clear, I do agree with your concerns about “in its current state, it will never be implemented across all browsers” that "It comes across initially as there’s no point using this - I don’t think that’s something we on MDN have the right to determine."

Perhaps we should instead state that "some vendors oppose the spec in its current form so it should be treated as experimental, and Google would love your feedback at LINK to help drive it towards cross-browser adoption", or some such thing.

But anyway, I think this needs a face-to-face discussion. Can I suggest that we do this in a separate meeting from the community meeting? I don't think we will be able to reach an effective decision about this in a small segment in a larger meeting.

[Rumyra]

I still have some thoughts for your reply @chrisdavidmills :) But yes - let's find a time to have a chat with everyone that cares (my apologies as this week is looking really busy) as I think it'll be easier to explain my position 👍

[hamishwillee]

See mdn/content#31942

FWIW I do see this as relatively useful for the constrained set of specs for which it applies:

1. I believe the rules for BCD are that if a browser implements something for 2 years it is no longer considered experimental. At that point you'd have no warning at a high level that the API is narrowly supported and that this is unlikely to ever change.
2. You might reasonably choose to implement something experimental if you know it is coming eventually and not otherwise.
3. It is IMO useful to point out areas where there are broad philosophical differences between browser vendor approaches to problems. This indicates likely churn and possibly alternative implementations for the same use case. FWIW that's what I'm most interested in - whether there is another API I should be using as well on other browsers that does something similar.

[chrisdavidmills]

Thanks, @hamishwillee. Last week we had a zoom meeting about all this and figured out a plan forward (the notes from that meeting will be posted here soon).

The contents of my PR are basically what we agreed on as a short-term solution. We are then going to work on the longer-term solution.

One key point you've brought up is number three — particularly the bit about highlighting competing APIs and alternative implementations. We should definitely think more about what that would look like.

[chrisdavidmills]

Notes: Jan 25, 2024 meeting to talk about standards position on MDN

Attendees: Chris Mills, Estelle Weyl, Florian Scholz, Jean-Yves Perrier, Patrick Brosset, Ruth John, William Bamberg

Notes

• (Ruth) Suggest we discuss the short-term solution and agree on that now…
  • Acceptable banner wording. What was wrong with:

    Warning: One or more browser vendors oppose this feature — in its current state, it will never be implemented across all browsers. See Standards positions for details of opposition.

    • Read as “don’t use this”
    • Needs to be more informative
  • Update:

    Warning: This feature is currently opposed by two browser vendors. See Standards positions for details of opposition.

    • Action: Chris to create PR to add this back
  • Worry about putting it everywhere
    • Not in many places anyway. 4-5 API landing pages?
  • Criteria for doing this:
    • When experimental does not fit the bill
    • When an API has (one or more) opposing standards positions
• …then plan for a longer term solution which could open a can of worms but
  • Create doc to capture all relevant discussions, thoughts and include a plan
  • be broader in terms of banners across MDN
  • Include user research
  • We’d have to include the ‘undoing’ of the short-term solution

Action items

• (Ruth) Add this content and conclusions of this meeting to How to represent standards positions for experimental/non-standard features · mdn · Discussion #463 (github.com)
• (Chris) PR this warning above onto the page where relevant
• (Chris) Add this to writing guidelines?
  • Make it clear - temp solution
• Next discussion:Long term solution?
  • (Ruth) Create PRD for people to review
  • Followup with discussion?
• Create timeline of decision making for this
  • Monday Feb 5 for PRD
  • Week for other above action items (Feb 1)
  • PRD reviewed - one month (March 5)

[chrisdavidmills]

I am going to close this, as I have been unblocked on the privacy sandbox docs standards position issue (short-term), and Ruth has created a way forward for the long term with the banners and notices PRD.