MDN Web Docs
Replies: 0 comments 30 replies
-
I think the word that best fits with what we’re wanting to convey is “discouraged”. “discouraged” is good because it lacks the baggage and formal connotations of “deprecated“ and of “obsolete” too. There are cases when specs have need to normatively assert formal status of a feature — and that spec need is met by “deprecated“ and of “obsolete”. But for MDN, we have no need to normatively (re)assert formal status of anything. Instead, we only have need to convey a less formal assessment of whether particular features are “not generally recommended” or “known not to be a best practice”. So “discouraged” is a good concise word to convey “not generally recommended” or “known not to be a best practice”. As far as relevant discussion elsewhere: TC39, for stuff that’s part of the language but that’s generally discouraged — in particular, much of the stuff in Annex B of the ES spec — has been internally using the word “icky”…
I think we have evidence it’s confusing to some readers, and that other readers object to some cases where we’re using it. But I think “discouraged” would at least not be as confusing, and at least not as objectionable. To help put it in terms of what developers are already familiar with: I think most developers understand what “code smell” means — and if they aren’t familiar with that term already, they get the interference — and I’m reminded of the Zappa quote about “Jazz isn't dead. It just smells funny”. What we need for MDN is something to flag cases of “This feature may not be dead yet, and may not be formally recognized as even being on its way to becoming dead, and in fact may never die — but… it’s kinda icky and it kinda smells funny”.
I believe we have a clear need to continue flagging the stuff we currently have flagged as deprecated — but I think we just need to come up with a better word for conveying it to developers. And short of going all the way to “icky” or ”smells funny”, I think “discouraged” conveys well what we actually are wanting to convey. |
Beta Was this translation helpful? Give feedback.
-
|
^^^ Yes. When I see "discouraged" I assume that I should not use the thing - but I do not assume a particular reason. Could be a formal specification deprecation ("on the pathway to removal") or could just be "not a good idea according to us". Usually I'd hope for additional context to be provided for something that it discouraged: discouraged because .... By contrast I see deprecation as having some formal meaning, and spec driven. I think globally replacing the word a loss of useful information. That might be OK, but it should be a decision we deliberately make. Had a case with @ericwbailey recently around something to do with Aria where the feature was discouraged but not deprecated. In that case we replaced the deprecated macro with a warning note that captured this "discourage use". EDITED: In other words, I'm not so worried about people's issues with the meaning of deprecation - whether or not they think it means "on the way to removal" they will understand it means "you should not use this". I'm more worried they might think that discouraged is a personal opinion of MDN. |
Beta Was this translation helpful? Give feedback.
-
|
To add a little more color to this circumstance, the HTML element in question is considered actively harmful to assistive technology, as it negated roles for a common navigation method. I think "discouraged" is a good term, but I'm also wondering if we need a term for something that has this strong of an adverse effect. It feels separate from something that can still technically function due to compat, but isn't considered best practice anymore. I feel many developers will grab something that technically works and not read the fine print, so that's my main concern. |
Beta Was this translation helpful? Give feedback.
-
I’m not aware of any actual "not a good idea according to us" cases — that is, where something in MDN has been arbitrarily flagged a feature just because somebody personally felt it wasn’t good. I think there’s always a good reason for some feature having been flagged — and in many cases it’s not because a specification has formally marked the feature has deprecated. Part of the reason that “deprecated” is messy and complicated is that specs don’t consistently use the term to mean the same thing — or don’t even use it at all. And that creates confusion for developers. But rather than just assert that, I guess it’s more helpful to look at concrete cases in specific specs. So here are two concrete cases — one from the ECMAScript spec and one from the HTML spec. 1. ECMAScript specConsider mdn/content#5509. The OP for that issue asserted that MDN shouldn’t be flagging And they are right. The ES spec doesn’t clearly mark it as deprecated — nor, in that section where it’s defined, have any language warning developers not to use it. For a developer reading the spec to start to understand more of the context, they’d need to think to go look at https://tc39.es/ecma262/multipage/additional-ecmascript-features-for-web-browsers.html#sec-additional-ecmascript-features-for-web-browsers — the intro for Annex B of the spec (the spec section that feature is in) — and read the note at the beginning of that, and notice the parts that say:
…but nowhere even there does the word “deprecated” occur. In fact nowhere in the entirety of the ES spec does it flag anything as “deprecated” — nor “obsolete”, nor any other metonym. And even in a case such as the
OK, so in our case, the https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto is documenting the accessor, thus it’s appropriate for us to flag it. But then we’re back to the fact that we’re currently flagging it as “Deprecated” despite the fact that any developer can go in read the spec and see that it’s not formally marked as deprecated. So the closest we can get for this really is “Discouraged”. 2. HTML specThe HTML spec also never flags as anything “deprecated”. Instead it uses the stronger term “obsolete” (which by policy we’re no longer using in MDN…), in combination with “(non)conforming”. And the Obsolete features section of the spec subclasses those obsolete features into “obsolete but conforming” and “obsolete and non-conforming”. But anyway, that’s actually all very clearly and precisely defined. For MDN purposes, it’s clearly appropriate for us to flag both the “obsolete but conforming” and “obsolete and non-conforming” features as “deprecated”. However, the HTML spec contains other cases which are not nearly as clear. For example, consider Among the
In other words, none of those features are actually useful for anything in practice — because they always return the same hardcoded string, regardless of which browser a user is running — and it’s appropriate to warn developers not to try to use them for anything. They’re literally useless. Yet, the HTML spec doesn’t put them into the “Obsolete features” section, nor does the HTML spec flag them in any way which makes it clear to developers that they shouldn’t be used. So for MDN, what should we do with them? As with the ES spec cases, flagging those as “deprecated” conflicts with how the spec itself categorizes them. And in particular, for those cases, it’s inaccurate for us to show warning text that includes:
…because So that seems like another case where the closest we can really get is “Discouraged” or some such.
That seems like another great example of where having a Discouraged flag would solve a problem. And to be clear about something: I think the Discouraged flag could cover both things we need:
In other words, we can use “discouraged” in the broader sense that also includes “deprecated” and “obsolete”.
I think in most cases we’re already doing that carefully and consistently — for example, the ARIA case you mentioned, or something like https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto (which has more than 130 words of specific warning text), or something like https://developer.mozilla.org/en-US/docs/Web/API/NavigatorID/appName (which has text saying This property is kept only for compatibility purposes and Do not rely on this property to return a real browser name. All browsers return "Netscape" as the value of this property), and so on.
For both sets of cases we’re considering — both the “there’s a spec which clearly marks this feature as deprecated”, and the gray-area cases discussed here — I cannot recall any feature we have flagged in an MDN article without some specific text explaining to developers why they should avoid that feature. That is, I can’t think of any cases where it’s not already clear that the article isn’t just asserting something that’s a personal opinion of MDN. That said, I’m not convinced there aren’t any such cases of articles that lack a clear explanation for a feature being flagged — in fact I’m nearly certain we must have some (and I wouldn’t be surprised if today I actually now come across one…). But I think solution to that is to deal with them case by case as we notice them, and make sure they get updated with good explanations. But the core problem remains that we’re currently flagging many of the gray-area cases as Deprecated — for example, the |
Beta Was this translation helpful? Give feedback.
-
|
It sounds to me like there's a general good feeling toward using "discouraged" to mean "in some way indicated by an authority—a standards body, usually—that the discouraged thing is officially disfavored" and a consensus that we shouldn't editorialize, if we can help it. Perhaps we could experiment with "discouraged" in the scope of BCD (e.g., revise the compat schema to define the current Also, good news on the ECMAScript front, specifically: it looks like they'll be adopting some "legacy" terminology to formalize "icky". I learned that as a consequence of my PR to get a warning applied to |
Beta Was this translation helpful? Give feedback.
-
|
@sideshowbarker @ddbeck FYI this came up again today here: nodejs/node#39581 (comment) Has this progressed at all? |
Beta Was this translation helpful? Give feedback.
-
|
mdn/content#4866 relates to another grey-area feature: The DOM spec doesn’t mark it as deprecated — all that is does say is a comment in the IDL: boolean isSameNode(Node? otherNode); // legacy alias of ===The implication of “legacy alias of ===” is “You shouldn’t use |
Beta Was this translation helpful? Give feedback.
-
|
Like my |
Beta Was this translation helpful? Give feedback.
-
Yes, I’ll bring it up with Anne |
Beta Was this translation helpful? Give feedback.
-
|
For the record here: For the ES spec, TC39 adopted and documented the use of the special word/flag Legacy — for flagging cases in the spec of features that they want to warn developers away from. https://tc39.es/ecma262/multipage/conformance.html#sec-conformance
|
Beta Was this translation helpful? Give feedback.
-
|
Legacy sounds like something that will stick around. We need a term that sounds like it's going away. |
Beta Was this translation helpful? Give feedback.
-
|
It's a step in a good direction for the spec to have that definition. Pity it doesn't spell out more clearly: "prevents their removal from this specification at this time". For MDN I prefer "discouraged" if we are keeping a single un-nuanced "we don't think you should use this". |
Beta Was this translation helpful? Give feedback.
-
|
When a language discussion gets nowhere, I think it's helpful to look again at the thing it's trying to describe. Having written Chrome's own deprecations and removals column for the last six years, I think I can make a few generalizations. First, as a web developer, I don't care about a spec deprecation until a browser implements it. I don't know what other browsers do, but when Chrome implements a deprecation, we either build its replacement first, or we look closely at how much something is used in the wild. So the sequence in Chrome looks like this: Spec deprecation > [Replacement implementation] > Chrome deprecation(includes console warning) > Chrome removal Question: can't we just solve this with adjectives? "Spec deprecation" "Browser deprecation". |
Beta Was this translation helpful? Give feedback.
-
I wish we could. MDN uses deprecated to indicate things that might be neither, as per the discussion further up: https://github.com/mdn/content/discussions/5549#discussioncomment-837662 |
Beta Was this translation helpful? Give feedback.
-
|
The only case I know of was https://github.com/mdn/content/discussions/5549#discussioncomment-837662 - I'm assuming it's a bigger problem though than just one case, or we'd deal with as an exception. |
Beta Was this translation helpful? Give feedback.
-
|
I don't think that needs a word of its own that the reader may or may not interpret correctly. I think it needs a big fat blurb explaining exactly what the problem is. If that's the only alternative use case, then it shouldn't soak up a word that has broader use elsewhere, particularly since "deprecated" may not always mean "don't use now". In fact, in some cases it may say just the opposite. There are cases where for interoperability, a developer may need to write code that uses a newer, preferred API if it's available, and falls back to an earlier deprecated one when it is not. That's a long way of saying that "deprecated" sometimes, at least in the case of spec deprecations, means "use carefully" or "use sparingly." |
Beta Was this translation helpful? Give feedback.
-
|
@jpmedley If you read the first post, both individuals and specs are using deprecated to mean different things. @ddbeck You might want to loop back into the conversation. I don't want to be the person "defending" various options here when I don't actually have any strong opinion on this (other than we need clear common understanding of whatever terminology we use). I'm sure you have a much firmer grip on the relative options. |
Beta Was this translation helpful? Give feedback.
-
I'm for specifics and I'm not getting them. The original statement, which I keep getting referred back to, has no information beyond an assertion that something is so. |
Beta Was this translation helpful? Give feedback.
-
@jpmedley is the earlier TC39 "legacy" example not sufficient? It's a clear case where the spec is saying "don't use this" while also maintaining that the legacy features will never be removed from the spec (as part of a commitment to backwards compatibility). More broadly, I haven't had time to act on this in more substantial ways, though I think it's important and I want it to become a part of my planned efforts. That said, I'm still dealing with some onboarding stuff and some urgent matters, so I haven't been in a position to make a concrete plan yet. Responding to the thread in general, I think we need both "fat blurbs" and a schematic way to refer to things which are in the category of things which are deprecated, obsolete, legacy, and what have you. "Deprecated" is plainly misunderstood (or sometimes rejected) by readers (see: the last few questions about this within BCD's own issues). We use that term in lots of places and we really shouldn't, due to reader confusion. We also use that term as the schematic (as in BCD), where we shouldn't. We'll also need to accomodate changes within the category that doesn't require us to rewrite every time a convention changes For example, before July, TC39 never had a single deprecation formalism, but now it does. That probably didn't need to matter to the way we represented it to readers or the way we captured it in data, except that the term we used provoked annoyance or disagreement. I think "discouraged" wraps up a lot of this stuff schematically, but it's not an answer for the other pieces (I've got a more detailed take on how to do this, which I've written up on my own site. It's not a propsal to carry out the work, however.). We'll need a comprehensive effort to deal with this stuff. |
Beta Was this translation helpful? Give feedback.
-
I can live with 'legacy' for TC39 features because it's in the spec. I object to cases where it's not in the source. For example, Chrome uses the word 'deprecated' to refer to features slated for removal at a later date. To not mirror that term in BCD or on MDN is to introduce a possible source of developer confusion. I can imagine someone asking what's the difference between a Chrome deprecated feature and a Chrome legacy feature and, not knowing it's MDN's term, searching in vain for an explanation on a Google site. |
Beta Was this translation helpful? Give feedback.
-
|
@ddbeck Your PR for removing HTML Imports reminded me of this discussion. I understand removing this content due to lack of current and future support, but also am wondering if there is a need to document this content as having been a thing for the historical record? I would imagine it would have all the necessary surrounding content to warn about support. |
Beta Was this translation helpful? Give feedback.
-
|
@ericwbailey narrowly, I think reference documentation should be relevant to contemporary developers and we shouldn't make historical preservation an aim. Readers skim more than they actually read, so it's risky to keep full documentation around for things which are plainly unusable, even with warnings. That said, sometimes you need coverage on historic features to explain other, contemporary features (an example with More broadly, perhaps there's some value in a sort of feature graveyard document that very briefly acknowledges the historic existence of features or proposals and refers readers to contemporary alternatives. That could be good to write (and a better target for redirects), but it's also very difficult to prioritize, for hopefully obvious reasons. 😅 |
Beta Was this translation helpful? Give feedback.
-
|
Cool cool, thanks for the insight. I'm also team "design for skimming readers", so no arguments here. Perspective on what content needs to be kept for historical context is also helpful, thank you. |
Beta Was this translation helpful? Give feedback.
-
|
The two questions that most pop up associated with deprecated are:
It would be good if whatever we do here could answer either or both questions. The word "discouraged" does not answer these questions - it just tells you that you shouldn't be using it in an even less precise way. Just an idea - maybe we could do some of this this with options to the deprecated header, allowing the generated content to be changed to incorporate a precise definition of the term. So for
What I like this idea is that:
Another similar idea is that you can specify a clarification to deprecated, but it must always be a spec definition. So below "legacy" is the word used to describe the API in the spec (would love an url to spec too, but let's keep this simple):
Most recently this came up today in Issue with "CSP: block-all-mixed-content": Deprecated without explanation or suggested replacement. #9889 (answered) |
Beta Was this translation helpful? Give feedback.
-
|
AFA terminology, there are not a lot of replacement choices for "deprecated" that can be easily understood. While on the subject of "deprecated", I would also like to mention the following ...
|
Beta Was this translation helpful? Give feedback.
-
Last week, I had a lengthy conversation with @wbamberg, @Elchi3, @sideshowbarker, and others on some trouble with using the term "deprecated" on MDN and in BCD. I'm mostly writing this down to get it out of my head, but if there are others who are interested in this discussion, please point them to this discussion.
The questions that came out of that conversation came out to three parts:
I've got some additional background for each of these questions in the sections that follow.
What do we intend for "deprecated" to mean on MDN?
Since BCD drives a lot of the deprecated text on MDN (e.g., the tooltips on deprecation in compat tables), BCD's definition of deprecated happened to spur this whole discussion.
An interesting question here is: does BCD agree with other practices (e.g., adding deprecation banners) on MDN? As an author, do you typically use "deprecated" to mean anything else?
Is our use of "deprecated" understood by readers in the same way we intend it?
In mdn/browser-compat-data#10490, a contributor mentioned this Stack Overflow question: Is the JavaScript keyword
withreally deprecated?. The discussion there highlights some of the conflict: TC39 uses "deprecated" one way, MDN another, an argument ensues. I don't know if we have other (good) ways to find out what readers think "deprecated" means.To get a sense of the broader use of "deprecated", I asked in the Write the Docs Slack about how other tech writers are using "deprecated" (see my full notes for a complete breakdown of the discussion). The biggest takeaway there is that other authors often use "deprecated" to mean that something is on the road to removal, even if it never arrives at that destination. My conclusion is that MDN is doing something slightly unorthodox, but I'm curious if there are other perspectives on this.
Should we continue to use "deprecated" as we've been doing or consider adopting alternatives?
The Write the Docs discussion highlighted a key thing, which is probably of interest regardless of how we use "deprecated": when something is discouraged from use we ought to direct users to alternatives.
Apart from that, there are probably other words we could use in place of deprecated, if we think we're using deprecated wrongly. We'd need to come up with some alternatives and have a definition to go with it.
Related issues
https://github.com/mdn/yari/discussions/2905 - discusses using front matter to set deprecation banners
Beta Was this translation helpful? Give feedback.
All reactions