Figure out where we use tags and how much we can clean them up

[wbamberg]

In talking to @escattone we were wondering where and for what we use tags in MDN. Our tags were migrated wholesale from Kuma and in general are a real mess.

I think that now we don't expose them directly to users any more (?) but they are used in some macros. It would be good to understand which macros use them, and which specific tag values these macros are looking for, and whether we could clean out the other values.

[hamishwillee]

No idea. I recently cleaned up an old pre-kuma syntax that allowed you to list all pages that had a particular tag - "because we don't do that anymore"; that's pretty much the only use of tags that I would want.

[peterbe]

We do index them in Elasticsearch. For no reason, because you can't search for them through the query API (/api/v1/search?). :)

We certainly don't display them in any UI on the document page itself.

So I think they're only used for some macros. Sidebar macros in particular.

[peterbe]

One thing I've noticed is that if you think the English tags are a mess; wait till you see the translated-content tags. So often they are different!
If the sidebar rendering depends on the tags...;

1. The sidebars in translated content is going to suffer
2. Can't the translated-content just piggyback on their en-US parent doc?

[hamishwillee]

If the tags never appear in the UI, and we don't intend to show them in future, then there is no reason not to piggy back them off the en-US parent. In particular this is true because IMO it is desirable for sidebar navigation to be consistent across localisations.

But I'd be considering dumping them for sidebar navigation (and MDN) altogether. My "experience" is that there are better ways to build navigation. They do make sense for something like wikipedia where navigation is by category not "guided" (which is where I see the value of sidebars)

[jpmedley]

Something just struck me about this. Am I remembering correctly that I could previously click on a tag and see all the pages with that tag? If there's a way to look at stats of those URLs, someone should. Such stats may or may not be arguments for keeping tags, but they could be evidence of use cases that still need to be supported. For example, tags may have been the only way to see a complete list of all events.

[peterbe]

Something just struck me about this. Am I remembering correctly that I could previously click on a tag and see all the pages with that tag? If there's a way to look at stats of those URLs, someone should. Such stats may or may not be arguments for keeping tags, but they could be evidence of use cases that still need to be supported. For example, tags may have been the only way to see a complete list of all events.

In other words; "hold on before we kill all tags" :)

I'll let you content gurus hash it out but I can predict that it would be trivial to add a site-search, by tag. You can actually already search by prefixes. E.g. https://developer.mozilla.org/api/v1/search?q=foreach&slug_prefix=web/htMl
Now, there's no UI for doing this. Just saying how relatively easy it can be accomplished. It would be easy to add &tag=TAG1&tag=TAG2 to the search API. But I'd first need to do a bit of work to make the ?q=... parameter optional (if you supply other params) and then we'd need to decide if &tag=TAG1&tag=TAG2 means "TAG1" in doc.tags AND "TAG2" in doc.tags" or if it means "TAG1" in doc.tags OR "TAG2" in doc.tags".

[peterbe]

By the way @jpmedley @wbamberg if you have ideas how to get rid of https://developer.mozilla.org/en-US/docs/Web/API/Index I'm all ears. That page is so huuuge that it's omitted from the site-search and our sitemaps.
But perhaps it would be of value to the user to be able to replace that page with a link to the search search like:

<a href="/en-US/search?slug_prefix=web/api">Search all Web API pages</a>

...or something.

[wbamberg]

By the way @jpmedley @wbamberg if you have ideas how to get rid of https://developer.mozilla.org/en-US/docs/Web/API/Index I'm all ears. That page is so huuuge that it's omitted from the site-search and our sitemaps.
But perhaps it would be of value to the user to be able to replace that page with a link to the search search like:

<a href="/en-US/search?slug_prefix=web/api">Search all Web API pages</a>

...or something.

I believe that this page was only used by the doc status pages, which don't exist any more. But @chrisdavidmills might know better than me.

[chrisdavidmills]

By the way @jpmedley @wbamberg if you have ideas how to get rid of https://developer.mozilla.org/en-US/docs/Web/API/Index I'm all ears. That page is so huuuge that it's omitted from the site-search and our sitemaps.
But perhaps it would be of value to the user to be able to replace that page with a link to the search search like:

<a href="/en-US/search?slug_prefix=web/api">Search all Web API pages</a>

...or something.

I believe that this page was only used by the doc status pages, which don't exist any more. But @chrisdavidmills might know better than me.

I think Will is right here.

[jpmedley]

In other words; "hold on before we kill all tags" :)

You got the gist of it. I was going more for make sure we're clear on all the consequences before moving forward, and make sure we have new implementations for valid use cases such as (possibly) the events problem I alluded to above.

By the way @jpmedley @wbamberg if you have ideas how to get rid of https://developer.mozilla.org/en-US/docs/Web/API/Index I'm all ears.

That doesn't look like any index I've ever seen. It looks like something you'd create to make up for a lack of site search. I'll call this misnamed and something that should probably go away. I'd add that the site has no index at all. If you wanted an index, that's a different discussion, but I'm not sure we do.

Taking your question at face value, an index would be a list of links only organized under letters of the alphabet as headings. Links would ideally be subjects rather than to single pages. For example:

S

...
sensors

• API
• AmbientLight
• feature detecting
• Gyroscope
• ...
• using

This kind of thing would be more useful in the expository content where locations of answers to specific questions are less predictable. It seems like there would also need to be separate indexes for the various sections. For example, it's unlikely that someone searching for information on packaging an extension would need to see entries related to PWAs. In the reference material, it's not just redundant with site search, it's, in a way, redundant with reference structure itself. If I've spent any time at all in the reference, I can predict where all of these topics will be found.

The fact that the items in that page seem to all link to single pages reinforces my feeling that it was a site search substitute.

[hamishwillee]

The Deprecated, Non-standard tags in a page are used by the sidebar macros to auto-add the sidebar icon indicating this states. As discussed here: mdn/yari#3818 I think it a pain we have this info in tags, bcd and header macro. It should probably just be in BCD if possible imported into page, over-ridden by front-matter if present, and the deprecation header/other headers should be added automatically.

The only reason to not auto-generate the deprecation header is that it would be nice in cases where we have a deprecated API superseded by a clear replacement, if we could include the replacement as part of the macro.

That would allow removal of "state" tags.

[jpmedley]

we could include the replacement as part of the macro.

Should this be in the BCD instead? That would make the information available to all BCD clients and open use cases we haven't thought of yet.

[peterbe]

Not sure if this helps, but looking at the original issue here from @wbamberg ...

• CSSRef.ejs depends on:

  • Deprecated
  • Experimental
  • Overview
  • CSS Property
  • Selector
  • Pseudo-class
  • Pseudo-element
  • At-rule
  • CSS Data Type
  • Non-standard

• APIRef.ejs depends on:

  • Property
  • Method
  • Constructor
  • Event
  • Experimental
  • Non-standard
  • Non standard
  • Deprecated
  • Obsolete

• CSSInfo.ejs depends on:

  • CSS Function
  • CSS Data Type
  • Element

• cssxref.ejs depends on:

  • CSS Function
  • CSS Data Type

Actually. I'm going to stop there. There are many more macros that depend on them.

▶ cd kumascript/macros

▶ rg 'hasTag\(' --count-matches
APIRef.ejs:11
WebExtAPISidebar.ejs:10
CSSInfo.ejs:3
SubpagesWithSummaries.ejs:2
LearnBox.ejs:2
cssxref.ejs:2
CSSRef.ejs:12
SVGRef.ejs:1
InterfaceOverview.ejs:12

So it's pretty clear it's still relevant and important.
But it's only in KS macros. I don't know of any other place where they're exposed.

But all of this reminds me, I should write a translation-differences checker that makes sure the translated document's tags match the en-US one.

[jpmedley]

It may be a longer project than I thought, but I'm still in favor of moving to BCD when we can. It seems like CSSRef could be altered to read from BCD. It might also prove useful if event, method, property, etc. were the value of a type attribute in BCD. These are just a few examples.