How to deprecate content

[Ryuno-Ki]

This will resolve in mdn/yari#2903 as actionable summary.

From what I understand, at the moment, deprecation is done via macros, that render some EJS template.

Since we want to migrate to Markdown as main format for editing in the future, it's worth thinking about how we would deal with it in that world.
In my mind, that could be handled by a line in Frontmatter (deprecated: true or deprecated: 2021-02-14 or deprecated: ['Firefox 85', 'Chrome 90']) and then handled by Yari when generating the markup.

How would you approach it?

[ghost]

Sounds interesting to me.
In my opinion, we must distinguish from what is deprecated by the W3C and what is no longer supported by a browser. We don't risk creating too complicated data models if we know how the business logic works, us or others.
And above all even if we don't use Typescript on YALM we still try to be consistent with the data types spontaneously.
For example, in this case I would associate the word deprecated with the equivalent of a true or false in YALM, no Array or date. Rather for other data we add keys.

[peterbe]

From what I understand, at the moment, deprecation is done via macros, that render some EJS template.

What macro is that?

[Ryuno-Ki]

https://github.com/mdn/yari/blob/9e3e569ce8df374a50e343da791eb245420106e4/kumascript/macros/Deprecated_Inline.ejs

as mentioned by @hamishwillee in mdn/content#2086 (comment)

[ghost]

Pretending that we take everything from these JSON (browsers-compact-data) as an example, the macro is no longer needed and should be deleted?

[ghost]

https://www.w3.org/TR/html401/conform.html#:~:text=A%20deprecated%20element%20or%20attribute,in%20future%20versions%20of%20HTML.

According to this document, the deprecaded property should belong to the Element and Attribute class objects intended as articles in MDN that talk about an element or an attribute in HTML.
The note could simply state the status and reference the definition on the W3C specification unless there is an MDN article of its own that talks about this status.

Examples

• The feature documented in this article is deprecated.
• The element documented in this article is deprecated.
• The attribute documented in this article is deprecated.

---

It is perhaps not necessary to create a class for each type of Article but perhaps also just an article class that has an enumerable property of type (attribute, element, property, method, function, value). We need to think, we need the people of content. An actionable issue could be supporting the key in YALM or somewhere right to define the properties of the article object (a JSON, a meta tag if that's valid). Here too to reflect.

---

Also I was wondering if we can take the data from BCD in order to be consistent, we should analyze if they have it and redo a logic similar to the BCD table.

---

const MDN = { 
class Article {
  static title = new String();
  static content = new MDN.Content(); // 🤏
  static slug = new MDN.Slug(); // 👎
},
class Element extend MDN.Article {
  static deprecated = false;
 }
}
const article = new MDN.Element();
article.deprecated = YALM.deprecated;

Pseudo code ⬆️ (attempt to namespaces because the classes are pretty the same as the real Javascript classes documented 😑)

---

But at the moment there is a component called Article at the beginning of the template which you can add this if?

[ghost]

Yep.
Sorry.
One of the reasons it doesn't convince me is because it doesn't have a page or class on MDN.
Instead JSON yes.
This to me layman means potentially less hassle and less string manipulation.

• https://developer.mozilla.org/en-US/search?q=YAML
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON

[Ryuno-Ki]

Nothing is stopping you from adding it to a Glossary page or so :-)

[ghost]

In any case, do we already have a JavaScript representation of the Frontmatter?

[ghost]

Nothing is stopping you from adding it to a Glossary page or so :-)

For the moment JSON, XML and SQL are enough for me but I might change my mind. I see that GitHub also uses it for actions. I wait for an engineering intervention from above to understand if it is really recommended (Especially examples for parising in JavaScript.).

---

However, returning to the subject, does the decision here in this discussion also affect the CLI?

[ghost]

FTR
https://en.m.wikipedia.org/wiki/Single_source_of_truth

[hamishwillee]

I think it is better to generate lists of things like this dynamically (as stated elsewhere).

• The dynamic list doesn't necessarily have to work for every case to be better than what we have now.
• I'm not sure that this can be done as list from tags/metadata due to granularity - but perhaps it can (after all, even attributes often have their on page on MDN). [FWIW, I'd like dynamic lists from tags anyway :-) )
• BBD as suggested by Mattia - great idea, but BCD definitely doesn't go to the level of detail needed (even aside from other technical issues of integrating two markups.
• I'm OK for macros for this kind of thing - you have formalised markup you want somewhere anyway, and you slurp that up for lists. I don't mind that it doesn't render perfectly in markdown.

I'm hoping the dev team can give us some kind of direction here on what is reasonable to achieve with the tooling.

PS. Regarding "consensus" @peterbe - I presume you mean with the idea that dynamically generating a list like this is "a good idea"? Or do you mean with the precise approach?

[ghost]

Are You talking about validating HTML content against a kind of schema so we can have structured data directly from there?
I know that Is common in XML.
I can't imagine the whole thing well but the fact that a data is entered in only 1 point is good, even if this point is an HTML table formatted in a certain way or whatever.

[wbamberg]

FWIW I think we should use BCD for this. We already represent "deprecated" in BCD, representing it in two different places is a recipe for inconsistency.

One possibility here (in some structured content paradise) is that pages include the BCD query (e.g. "api.Navigator.sendBeacon") in the front matter. When the page is built, we resolve that reference and use it to build the BCD table and to add whatever markup we want to use to indicate "deprecated" (and anything else we could derive from BCD, like spec URLs).

BCD definitely doesn't go to the level of detail needed

I'm not sure I understand this, can you give an example?

[wbamberg]

To start with it's worth distinguishing what we've sometimes called:

• "banners", that are block-level things that appear along the top of the page they pertain to, like https://developer.mozilla.org/en-US/docs/Web/API/Screen/onorientationchange. Implemented using something like deprecated_header.
• "badges", that are inline things, usually icons, that appear next to links to the thing they pertain to. For, example in the applets link in the sidebar here: https://developer.mozilla.org/en-US/docs/Web/API/Document. Implemented using something like deprecated_inline.

Banners

For the "deprecated" banner that appears in pages like https://developer.mozilla.org/en-US/docs/Web/API/Screen/onorientationchange, we could do something like this:

• Simultaneously:
  • implement something in Yari that, if there's a browser-compat front matter item, and it has deprecated set, adds the deprecated banner to the page
  • update deprecated_header to be a no-op if there's a browser-compat front matter item
• Then at our leisure:
  • go through all our docs, moving the browser-compat query from the Compat macro into the front matter
• Finally, retire the deprecated_header macro.

We could also do the same for the "Experimental" banners that get added by the SeeCompatTable macro in pages like https://developer.mozilla.org/en-US/docs/Web/API/PaymentRequest/shippingOption.

There's more discussion of this general idea in mdn/stumptown-content#306, from a slightly different world though.

Badges

These are a bit different. In cases where the content is built (like sidebars), we could imagine doing something similar. If the sidebar builder is given the path to the file representing the page to link, it can also look in the front matter/bcd to get this value. Would be horrible for build performance though :). Or we could just not bother adding these icons to sidebars.

There are also cases where these macros are added by handwritten prose. These are usually lists of properties/methods, like https://developer.mozilla.org/en-US/docs/Web/API/BluetoothDevice#properties. Ideally we might eventually be able to generate these lists of links too, if we had a way to represent, say, the methods of an API, and then we could do the same thing there. But that's for the future.

[peterbe]

@wbamberg Regarding that rough plan for banners; would it be best to keep the {{deprecated_header}} string inside the doc? But what we could do, inside the deprecated_header.ejs code, is have access to the resolved BCD data and use that to determine whether to display or just return an empty string. Then, you can at least have full control of the placement of the banner.

I guess the other option is that Yari would take a stance and automatically inject the banner based on some business logic of parsing the browser-compat from the front-matter. But I guess its only option would be to inject it before any of the prose sections from the parsed KS-HTML (or Markdown).

[peterbe]

it can also look in the front matter/bcd to get this value. Would be horrible for build performance though :).

It might actually not be too bad. That stuff would be cached and stuff. We're most likely going to need to render those sub-pages anyway so with caching it wouldn't really matter if you do it when you render the page, or you render a page whose sidebar trigger that lookup.
I wouldn't count it out as too impossible.

[wbamberg]

@wbamberg Regarding that rough plan for banners; would it be best to keep the {{deprecated_header}} string inside the doc? But what we could do, inside the deprecated_header.ejs code, is have access to the resolved BCD data and use that to determine whether to display or just return an empty string. Then, you can at least have full control of the placement of the banner.

I guess the other option is that Yari would take a stance and automatically inject the banner based on some business logic of parsing the browser-compat from the front-matter. But I guess its only option would be to inject it before any of the prose sections from the parsed KS-HTML (or Markdown).

I think the banner should always be at the top, so it is better for Yari to inject it automatically. That's actually one of the big advantages of this proposal IMO - authors don't have to remember to include this macro and to put it in the right place. In Kuma, everything was done ad-hoc in content - banners, sidebars, next/previous links. In Yari it would be great to get away from this. I think of these banners (and sidebars too) as being more like breadcrumbs, say, than like page content.

[peterbe]

Excellent. I'm in favor of that.
Let me know via mdn/yari issues when I can help.

[hamishwillee]

BCD definitely doesn't go to the level of detail needed

I'm not sure I understand this, can you give an example?

I'm sure I had a specific case when I wrote that but I can't think of what it was now. There are at least some APIs though where the feature docs don't cover all functions, so there is nowhere to mark that a particular function is deprecated.

HTTP methods are commonly not in BCD if there is no clear meaning for "supported by a browser", so there would be nowhere to mark those if deprecated.

There are probably other things BCD does not cover at all but we still need to mark deprecation in docs.

Which is not to say I don't completely agree with at least attempting to do this. It's just that it might mean we have to document to greater breadth and depth in BCD than we have previously chosen to do.