Use of icons to indicate the status of elements, properties, and APIs

[schalkneethling]

In various areas, such as the sidebars, main content, and browser compatibility tables, we use icons as a means to indicate whether an element, property, or API is:

• Obsolete
• Experimental
• Non-standard
• Deprecated
• and possibly other statuses

Currently, this is used inconsistently in terms of the use of color; for example:

In the sidebar

In the main content

In BCD tables

These icons have created constant problems with the layout of the items in the sidebars that have yet to be solved.

• Inconsistent placement of icons yari#1721
• Wrapping of text (prototype properties/methods etc) in the left navigation panel yari#2221
• Sidebars yari#4033
• https://github.com/mdn/content/discussions/7535#discussioncomment-2710838
• Wrapping of text (prototype properties/methods etc) in the left navigation panel yari#2221
• Non-standard/Deprecated icons are not consistent yari#5571

These icons are also not exposed in an accessible manner, especially in the sidebars, for example, mdn/yari#5905

Kumascript macros

Several Kumascript macros exist solely to display these icons.

• https://github.com/mdn/yari/blob/main/kumascript/macros/Non-standardGeneric.ejs
• https://github.com/mdn/yari/blob/main/kumascript/macros/DeprecatedBadge.ejs
• https://github.com/mdn/yari/blob/main/kumascript/macros/ExperimentalBadge.ejs
• https://github.com/mdn/yari/blob/main/kumascript/macros/NonStandardBadge.ejs
• https://github.com/mdn/yari/blob/main/kumascript/macros/ObsoleteBadge.ejs

There may be even more that I am not aware of.

Conclusion

It seems that these icons are causing more problems than they are solving. As a result, this discussion is intended to come to a conclusion between readers, authors, and engineering as to how this information is best surfaced. Perhaps only showing these in the BCD tables using consistent iconography and colors? Perhaps a completely new approach is needed. Whichever solution is decided upon, we need to ensure that it is accessible to everyone.

[teoli2003]

We are trying to solve three goals here: conveying information, bringing more coherence to MDN, and better maintainability of the content.

1. Conveying information about the feature
   We want to tell the user to pay attention to this feature in five different places:

• On the feature reference page. This is usually done using a page-wide banner at the top of the page (out of the scope of this problem)
  

• In the sidebar. Here we have a list of all related features, and we want to allow the users to navigate easily it. Here knowing that a feature is deprecated or non-standard, they hopefully want to try first standard features, and only fall back to iconized features if they can't solve their problem. Currently, we use colored icons in front of the link.
  

• In the definition list of the interface. Similarly to the sidebars, we want to draw attention to the problem when the reader scans the definition list quickly.

• In the prose. When reading some prose, especially prose that has not been updated recently and is outdated, we want to drag their (and ours) attention that what is said is outdated. We don't do this now, but having the icon next to the link would achieve this. (Ideally, this would be detected by Yari when generating the site, without a need of modifying the content or relying on a macro!) For example, all the links there lead to deprecated (and removed) features:

• In the browser compat table. That's, in my opinion, the neater:

2. Coherence in the way we annotate features

• When using a website that is coherent, the reader feels at ease: they know the meaning of the symbol, they are used to the wording and they know where to find the information they are looking for quickly.
• We want to have marks that mean the same thing, that have the same visual aspects (type of icon, colors), and that will always be where they should be. We don't have this right now.

3. Maintenance of data

• The source of trust for this data is mdn/browser-compat-data. We should update the values there, and, automatically, after a week or less, the icons are updated on MDN.
• We have two other ways to store this data on MDN. They predate mdn/browser-compat-data and must go away:
  • Sidebars read the Tags: in the Yaml of each page and then apply the correct icons.
  • Definition lists have hardcoded (and unmaintainable) macros.

So I do think, we should unify all this. This is an intricate project and in order to succeed, feature creep should be avoided at all costs: for example, merging this with a redesign of the sidebar, even if this is needed, will likely make this project too big and fail.

I do like the way the icons are displayed in the browser compat table, even for multi-line entries. I think we should unify this: same colors and behaviors (on hover for example), immediately right of the term (and not left like in the sidebar), and the nice way they handle multiline entries:

Maybe something similar can be done for sidebars!

I would be open to another solution than displaying icons for displaying this info, but I don't have any. We tried labels before, and it didn't work.

[wbamberg]

Great comment @teoli2003 , you saved me from trying to organize my thoughts! Especially this:

The source of trust for this data is mdn/browser-compat-data. We should update the values there, and, automatically, after a week or less, the icons are updated on MDN.

We have two other ways to store this data on MDN. They predate mdn/browser-compat-data and must go away:

• Sidebars read the Tags: in the Yaml of each page and then apply the correct icons.
• Definition lists have hardcoded (and unmaintainable) macros.

I feel like the rest of it - deciding how to represent these statuses to readers - is a quite separate problem from how to maintain and update the data.

For the "banners" (indicators on the page itself) we are not so far from being able to do this, with the big caveat about what do we do for pages that don't have a corresponding BCD entry, like API overview pages (this is the same issue we currently face for specifications). For the "badges" (indicators attached to links to the page) it's trickier.

[hamishwillee]

Great summary. Also strongly agree that there needs to be a separation of data storage and presentation. Ideally just one place for it to be stored, which would be the BCD, with fallback to page metadata if no BCD entry exists.

Some minor asides

• Obsolete should no longer appear anywhere. The macros may exist but the concept got rolled into the deprecated catch all some years ago.
• Read-only for properties is also useful tagging. You might decide to have this as metadata too, and do icon iff the property is displayed as the definition in a definition list, sidebar etc.

[teoli2003]

I think obsolete is really a thing of the past on mdn/content:

• rg "\{\{ *Obsolete" -i -l leads to 0 entry (Yeah!). This has been confirmed by @queengooborg who marked them as deprecated in yari: they'll rise a flaw if somebody try to use them).
• rg "\- Obsolete" -i -l (detecting mostly tags) leads to 1 entry that is MDN meta-docs about what is deprecated what is obsolete.

It is a different story on mdn/translated-content.

The read-only information should be read from a reference source, and added automatically in definition lists (as well as in the first sentence), and I think we should get the info form w3c/webref where it should be stored.