Tags - should only one of deprecated, experimental, non-standard be used?

[hamishwillee]

We agreed that if a page is deprecated then it should ONLY have the deprecated header, even if it is also experimental or non standard. The reason for this was that the headers are big and quite prominent, and we really only need people to know the use of the API is discouraged, not exactly why (at the cost of the ugly banner and "wait" before user gets to content).

Should this rule also apply to tags - came up in a discussion? i.e. if you have added deprecated tag, should you then remove the experimental and/or non-standard tags?

My thinking is that I'd be OK with this, but we don't need to. The tags do add little icons in the sidebar menu, but having the extra information in not "disruptive".

Further, if we were to do this I'd rather do it via the macro than changing markup (and even further, I'd rather it got the data from BCD if present).

[teoli2003]

I think that something that is deprecated is no more experimental so both shouldn't coexist (like in bcd?).

But maybe the other cases may exists together?

[hamishwillee]

It is useful for someone to know that something was formerly experimental and now deprecated, as opposed to fully part of the standard and then deprecated?

And how do you feel about "non-standard"

[Ryuno-Ki]

Can you point me to what you refer to by „tags” here?
My first thought was on those elements in the frontmatter.
I haven't caught up yet where they get be consumed. From the initial post I would assume, in the sidebar when listing the different items.

[hamishwillee]

Yes, I mean frontmatter tags. The icons in the sidebar come from the tags Deprecated, Experimental and Non standard (though not sure of formatting on last one)

[Ryuno-Ki]

Thanks. So

if you have added deprecated tag, should you then remove the experimental and/or non-standard tags?

sounds like mutually exclusive options. That is, something cannot be experimental and deprecated at the same time.
Which would imply to me that it should be considered a flaw at that point.

As far as I can tell, non-standard and experimental can be derived from spec status and browser implementation (BCD?). deprecated / discouraged is an odd one out here. Something can be supported, even specified but still be deprecated.
Experimental APIs can be non-standard (I'd assume, some of Project Fugu would fall into this category).

Hmm … good question. I need to give this more thought.

[hamishwillee]

Cool. I'd be happy for all the information be present, and the toolchain to work out what is best to display.

[janbrasna]

There are cases when nonstandard & deprecated appear together quite often:

or

but just yesterday I've run into all three at the same time:

or (including bcd table w/ flags)

(what's weird here is how "nonstandard" is omitted from the actual xref in the main content, and sometimes even on the target page itself…)

Examples of nonstandard+deprecated+experimental:

• https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-CH-Lifetime
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-DPR

[hamishwillee]

@schalkneethling This discussion may be of interest to you. The experimental, deprecated, non-standard frontmatter tags result in auto-generated sidebar icons. The question is whether we should display all these icons, or just display one, indicating "this may have some issue, avoid if you can". I don't think it does any harm to have all of them, but we should make a decision, and if we are only going to display one, then IMO the toolchain should work out which one based on the set that are present in the front matter.

PS In the post above note the comment "What's weird here ...". The learning here is that this kind of information should only have to be set in one place. At the moment the page banner is applied separately from the frontmatter, so it is easy to get out of sync. This should be from BCD or from tags, but where ever it is from, it should propagate to the other places it needs to affect.

[janbrasna]

There's now a rather flexible system of documenting the flags via banners (those two links show one case of "warning" for nonstandard at the top of the page, and one case of "note" for nonstandard at the bottom) — I'd like to put that in context of "deprecated" meaning deprecation (pun intended) and related discussion around https://github.com/mdn/content/discussions/5549#discussioncomment-1499176 — i. e. the system of deprecation macros proposed, contrasting with more flexible freeform banner texts with deprecation reasoning customised for each case, as noted earlier in that discussion — just to complete the big picture.

[hamishwillee]

IMO the banners should automatically be auto-applied based on the tags for most cases. But it would be great to be able to override them if you were able to provide additional information - for example if something that has been superseded I would really like it if the replacement was listed. Right now you end up adding a banner for the deprecated then a note explaining why. Of course maybe the replacement should also be in a tag.

[janbrasna]

My thoughts exactly: have defaults that yield consistent results even when the author doesn't posses the past experience that would help them choose the most agreed-upon way of presenting the information in a banner… while still allowing some verbose reference for cases where a reason for obsolescence, spec update or revision, or replacement solution needs to be provided (to make sure any such flag is not interpreted as an "MDN opinion", but rather a sourced observation).

[schalkneethling]

Hey All, to get to an actionable conclusion specifically regarding our use of these icons across MDN Web Docs, I started the following discussion. Your participation will be much appreciated. #69