Where should we represent metadata on MDN?

[wbamberg]

We have a discussion thread about what kind of metadata we want to have for MDN pages. This one is about where we should represent it.

As we talk more about adding metadata to MDN, and using it more to build bits of the page, one question comes up: should we keep it in the page front matter or in BCD?

Right now we have some in BCD:

• spec URL
• experimental
• deprecated
• standard track

...and some in front matter:

• page type
• title
• spec URL (again)

We're also talking about adding more metadata, although some of this could be sourced from the IDL via webref, including things like:

• secure context required (in IDL)
• available in workers (in IDL)
• needs permissions
• short title
• next/previous links, or page weight, for ordering multi-page guides
• property properties (writable, enumerable etc)
• etc

Should these things live in page front matter or in BCD?

---

First, for items that can be found in webref/idl, I think we should use that. Otherwise we're just making our own copy of the data, asd we used to do for CSS formal syntax.

For items that can't be found in webref/idl, I think we should prefer front matter, unless the data is complex and long (like browser compat data itself).

Reasons for this:

• I think it's easier for maintainers to add or edit a key in front matter when writing/updating a page. Our experience with mdn/data is that maintaining metadata in a separate repo is difficult for contributors. I think it would be quite bad to have an MDN contribution model which is heavily based on editing JSON structures.
• Not all pages have a corresponding entry in BCD. Sometimes this is just because it's not been created, but sometimes it's because BCD's structure doesn't reflect MDN's. For example, web API overview pages don't exist in BCD. So when one of these pages needs a metadata value, we need to support it in front matter as well, as a fallback. We have seen this already with spec_urls, for instance, which can now live in either place. This is quite bad, because it's very confusing for contributors, and it's not clear what does or should happen when the thing exists in both places (for spec_urls, I believe that both entries get rendered, even if they are the same). This also cause problems if we want to use spec URLs to look up data in webref/idl. When there are two, which one do we use?

I think when the data is inherently quite complex and long it is better to keep it out of the front matter. For example, it would be bad to have the compat data itself in front matter.

[teoli2003]

Both mdn/data and non-bcd info in mdn/browser-compat-data were added before the YAML header era.

For new structured data that can't be inferred from other sources (bcd or webref, for example), I think we should put them in the YAML header of the page.

Do we want to move existing data (like the one in mdn/data) to the MDN page header? As you said, this would ease contribution and make it clear where the data is.

[hamishwillee]

Not much to add.

• Yes, if data is in IDL let's pull it in automatically
• If data is in mdn/data and can be represented logically in page metadata that would be much better.
• I'd like to kill the "tags" metadata at the end of this process - so if we have data in tags like experimental, deprecated, standard track then IMO it should be in a specific metadata type - probably one for each to make a clear mapping if the data is also in BCD.

W.r.t. BCD vs front matter info my (probably unpopular) leaning is that BCD should be a master copy. Mostly because:

• It is deployed to multiple places, which I think rely on information like the spec and experimental/deprecated status being present.
• It is a much smaller and more contained dataset to mine for this information.
• I think it is easier to maintain all that data together.

I think we should get the data from BCD where we can and otherwise use front matter keys. If there is a conflict, the front matter keys should win. I think that the end result will be a relatively small number of cases where users need to think about things like deprecation and so on.

[Rumyra]

I agree with @hamishwillee here:

• If we can get it from webref we should
• I think trying to keep the amount of data we have in frontmatter as small as possible for author simplicity, with the balance of it being else where considered (for instance the complexity of mdn/data is more than a frontmatter key, but bcd possibly holds a few frontmatter keys so prefer bcd over frontmatter)

I sort of see 'is the data to do with the page' ie title, slug, page-type - should be in frontmatter, 'is the data to do with the spec' - should come from webref/bcd - this isn't a perfect science however because @wbamberg rightly points out we have out lying pages (like web api landing pages) - with this though I wonder whether the work @ddbeck is doing on grouping web features might be useful (in the long run) https://github.com/ddbeck/common-web-feature-mockup/tree/main/web-platform-features

[wbamberg]

I'm surprised you say keeping metadata in BCD is better for author simplicity. I think it's a lot easier for authors to have a few keys in front matter that are alongside the content than to update them in a big JSON file in a separate repository.

And it means I can make a change in front matter, run yarn start, and see the updated page, which I can't in BCD.

It also makes our source more readable: looking at index.md you could understand a lot about the feature by reading the front matter. I think source readability is really important for maintenance: it's much easier to see where errors are coming from and to fix them.

If there was a lot of metadata I would agree, and I do agree that browser compat is too long and complicated to fit into front matter. Which is why I started https://github.com/orgs/mdn/discussions/226 - I wanted to get a sense of how much metadata we would want. The implication of that is that there isn't much: we've thought and talked about metadata a lot (and have had some form of metadata, as tags, for years) and the same few things keep coming up.

In general I think front matter is better for humans, and BCD is better for machines. But front matter is readily convertible to a machine-readable format - it's easier to make front matter machine-readable than to make BCD human-readable.

I sort of see 'is the data to do with the page' ie title, slug, page-type - should be in frontmatter, 'is the data to do with the spec' - should come from webref/bcd

Page type at least is closely tied to the spec, and to other metadata items. I think page type determines which other metadata items a page might need. And for reference docs, title is closely tied to the spec as well.

[hamishwillee]

BCD is the right place for data if it has to do with compatibility. Historically data appearing in in both MDN and BCD has been far more accurate in BCD. Most important, if there are multiple copies of something, then one of them has to be clearly the "master". BCD has historically been ahead of MDN in docs, and it is good to have the compatibility data even if we don't have docs yet - so most of the stuff already in BCD is probably better there, unless we start to allow stub-metadata only docs in MDN.

Other than that I'm happy for data to be in the page. My concerns there are around making sure the set of possible metadata doesn't grow beyond what authors and reviewers can reasonably be expected to understand and maintain.

One thing I'd like to do sooner rather than later is move towards removing all tags.

• Update our tag advice to remove mention of any tags that are not required for sidebar and icon generation.
  Specifically, remove the advice to "add any terms that might be useful for searching, including the API name itself".
• Run a project to strip those all out.
• Move experimental, standard, etc to their own front metadata values, and fix up macros to use those. Strip those out too.
• Start using the page type metadata - strip out method, property etc .
• At this point we now have no tags.

[wbamberg]

BCD is the right place for data if it has to do with compatibility.

Yes, agreed.

Historically data appearing in in both MDN and BCD has been far more accurate in BCD.

This is true because MDN has been a Wiki, but being in GitHub, and being able to use structured content (front matter) means we can make MDN much more well-organized. I can't find it now, but I believe someone in the dev team (Peter?) made a tool that scrapes front matter into a JSON blob.

I think page types are a foundational part of that, because we can define the data items that can/must be attached to particular types of pages, and we can have that in CI.

Most important, if there are multiple copies of something, then one of them has to be clearly the "master". BCD has historically been ahead of MDN in docs, and it is good to have the compatibility data even if we don't have docs yet - so most of the stuff already in BCD is probably better there, unless we start to allow stub-metadata only docs in MDN.

I do agree that having one copy be the master is important (and only having one copy is much, much, better still).

Other than that I'm happy for data to be in the page. My concerns there are around making sure the set of possible metadata doesn't grow beyond what authors and reviewers can reasonably be expected to understand and maintain.

I agree as I said that if we have lots of metadata it gets unwieldly. I think one advantage we have with MDN is that it's a very mature project, so we should know what kind of stuff we need (just like with Markdown, we know which extensions we're likely to need). As I say, the same few things keep coming up.

One thing I'd like to do sooner rather than later is move towards removing all tags.

• Update our tag advice to remove mention of any tags that are not required for sidebar and icon generation.
  Specifically, remove the advice to "add any terms that might be useful for searching, including the API name itself".

• Run a project to strip those all out.

• Move experimental, standard, etc to their own front metadata values, and fix up macros to use those. Strip those out too.

• Start using the page type metadata - strip out method, property etc .

• At this point we now have no tags.

Yes, I'd love to do that.

[hamishwillee]

Sounds like we're more or less in "violent agreement" then. The tags annoy me - added https://github.com/orgs/mdn/discussions/294. I'm a bit worried there might "hidden uses" for some of them.