Question: Difference between "deprecated" and "obsolete"

bershanskiy commented 5 years ago

The MDN site uses two words "deprecated" and "obsolete", while this data repository uses only "deprecated". I would like to make BCD and the site articles consistent (either remove word "obsolete" from the site or add status.obsolete to BCD).

Example: BatteryManager and its elements are marked "deprecated" in BCD and "obsolete" on the site. So which one is it: deprecated or obsolete? One would have to look at the BCD table values to decide: it's perfectly usable in Chrome while not accessible in Firefox.

I believe this distinction is unnecessary and site should use only "deprecated" (replace all "obsolete" with "deprecated") because:

For most purposes, both "deprecated" and "obsolete" mean the same thing -- "look at the compatibility table and do not use this feature in any new code and migrate old code to newer alternatives ASAP"
The word "obsolete" is rather vague because different browsers remove different APIs on their own timeline.

Benefits of standardization

I would like to change a few macros to automatically insert experimental/deprecated/non-standard indicators based on data from BCD repo. For example:

To references to other pages DOMxRef and similar E.g., DOMxRef("thing", true) will insert the reference and the status icons, while DOMxRef("thing", false) and DOMxRef("thing") would not to maintain backward compatibility.
At the top of the pages that have their own MDN pages. E.g., if Compat("api.thing") has status.deprecated set to true, then the page linked to at mdn_url should have a {{deprecated_header}} on top.

chrisdavidmills commented 5 years ago

We are not supposed to be using "obsolete" on MDN any more — we came to the conclusion of just using "deprecated" a while ago, as the difference in meaning was confusing people, and just "deprecated" is good enough for most web developers. Any instances of "obsolete" that you find on MDN are not still there intentionally.

Hence BCD also just using "deprecated".

In terms of automating the display of "deprecated" notices from BCD, yes, this would be a good idea, and I think this has also been talked about before. @Elchi3 , I believe this is part of the "browser compat ribbon" project? (I can never remember the official name!)

Elchi3 commented 5 years ago

Yep, the term "obsolete" is deprecated on the MDN site :laughing:

@Elchi3 , I believe this is part of the "browser compat ribbon" project? (I can never remember the official name!)

I'm not sure if it is included, but you can provide your feedback in the issue that is determining our warning algorithm https://github.com/mdn/sprints/issues/1668

bershanskiy commented 5 years ago

Any instances of "obsolete" that you find on MDN are not still there intentionally.

Good to know. So I'll try to replace "obsolete" with "deprecated" where appropriate while doing other tasks.

bershanskiy commented 5 years ago

@Elchi3

I'm not sure if it is included, but you can provide your feedback in the issue that is determining our warning algorithm mdn/sprints#1668

Thanks for the link, it is definitely relevant here. However, it's about the table colors and browser support (so probably mostly browser version numbers) and I wanted to just make the text inline icons consistent with the BCD tables by automatically generating the icons based on the BCD status values. let me clarify with examples:

Disclaimer: obviously, I draw error examples from the lesser-used parts of MDN that contain more errors; however, these examples are still valid because the automatic status icon insertion would remove this class of errors altogether.

Automatically insert warning plaques on pages corresponding to BCD objects

Let's look at BatteryManager I linked earlier. mdn The api.BattryManager.__compat.mdn_url is https://developer.mozilla.org/docs/Web/API/BatteryManager, which means all articles at URLs like https://developer.mozilla.org/[locale]/docs/Web/API/BatteryManager are about BatteryManager. Also, api.BattryManager.__compat.status.deprecated is true, so the page should have a "deprecated" plaque at the top. Similar logic applies to experimental and standards_track.

Note that this can be done by either:

actually inserting the "deprecated" header into the article and every translation of it. This is possible even right now; I can do it myself right now, but do not see it as meaningful use of time and MDN server resources.
automatically inserting the header during page generation. I prefer this method because it:
- guarantees the most consistent and up-to-date statuses (inserted on every page generation)
- does not require any work from individual translators, reduces maintenance burden
- allows you to actually remove "obsolete" headers from MDN with minimum effort: first, automatically insert experimental/deprecated/standards_track status plaques based on BCD and then make "obsolete" plaque macro into a noop.

Automatically insert warning icons on links to pages corresponding to BCD objects

Let's look at Navigator: mdn

Currently, MDN links to other parts of MDN with macro links, e.g. like {{domxref("Navigator.battery")}}. Sometimes (but not always), editors insert inline status icons, but they do it inconsistently. In the screenshot we see:

NavigatorID.appVersion has status that indicates no warnings are necessary, but we see {{experimental_inline}} icon.
Navigator.battery.__compat.status.deprecated is true, so it should have a "deprecated" icon.

This can be done in two ways as well:

by editing every article (including translations) Again, not my preferred choice, same reasoning.
by extending the link macros to insert the status icons and then editing the articles to use the new functionality My preferred solution. I propose another optional boolean argument for the link macros (so that the existing macros keep working, but we -- or rather I -- can slowly replace them). E.g., {{domxref("thing")}} and {{domxref("thing", false)}} would behave as they do now (for use in text), but {{domxref("thing", true)}} would also insert the status warning icons (for use in lists like on the second screenshot).

My proposal has a different goal than the linked issue. The linked issue proposes a change in how the tables are displayed, while I want to just automate the insertion of deprecation warnings. What I propose might eventually come in handy with that issue down the line, but it is not blocked by it. If anything, the linked issue would be blocked by this.

bershanskiy commented 5 years ago

TL;DR: Closing this because the question is answered: "obsolete" term is obsolete itself and should be replaced with "deprecated".

Elchi3 commented 5 years ago

Thanks for all your work @bershanskiy ! :100:

mdn / browser-compat-data