What metadata do we want for MDN pages?

[wbamberg]

Preamble

We talk from time to time about parts of MDN content that could usefully be represented as metadata.

There are many aspects of a web platform feature that are well-represented as data, and that want a very consistent presentation in our documentation. For example, to indicate whether a feature is only available in a secure context.

The worst way to do this is to have some prose in the Markdown source saying something like "This feature is HTTPS-only". This is bad because it's a burden on the writer to ensure that the same boilerplate text appears in the same way, in the same place, on every page. When writers make mistakes here and the text diverges, it's bad for readers. It also becomes hard for us to figure out which web platform features have these aspects, if we want to change the way we represent them.

A better option is to use a macro. This keeps the content consistent and makes it easier for us to track the places the content is used. But macros are a bit limited in what they can do to a page: they can only embed some HTML in the place they are found, and they combine the data (the fact that, say, a feature is secure context only) with the way that data is presented to readers.

So the idea is that we represent things like this just as data, and the platform decides how to represent that in the page.

What metadata do we want to have?

To have a coherent plan for this I think it would help to try to make a list of the metadata items we might want for a page. I think also, different sorts of features would have different sets of metadata items, and that's where this intersects with page types.

I'd like, for now, to postpone the discussion about where we should keep this data. I hope it will be easier to answer that once we have a better idea of what data we need to keep.

To begin with:

• just about all features:
  • experimental
  • standard-track
  • deprecated
• Web/API features:
  • needs permissions X, Y, Z
  • needs secure context
  • needs user activation
  • available in workers

[teoli2003]

• Corpus of guides where the order is important:
  • Previous page in corpus
  • Next page in corpus
  • Top page in corpus

(These would simplify, even allow us to get rid of the macros like {{NextPage}} and co, and likely sidebars.

[wbamberg]

We previously discussed using weight for this: https://github.com/orgs/mdn/discussions/124. That's more concise but less explicit.

"Top page" seems quite repetitive. I wonder if it would be enough to rely on breadcrumbs in pages like https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events.

[Elchi3]

Thanks for starting this discussion!

There are probably a lot of things we could collect into metadata. It would be good to come up with requirements, so that we are clear if something is qualified for metadata and if it is worth the effort. Something like: We will offer this as metadata, because:

• There is an internal need to get rid of an existing, weird macro or data structure
• We'd like to be consistent about how we present information/data on the pages
• External data consumers have shown an interest in using this data point

Another example, for API property & JS property pages (web-api-instance-property, web-api-static-property, js-instance-property, js-static-property):

- writable: true | false
- enumerable: true | false
- configurable: true | false

(this would replace the js_property_attributes macro)

[Josh-Cena]

These could come in joint with the JavaScript page-types work? (I don't know if anyone's championing that.)

[wbamberg]

These could come in joint with the JavaScript page-types work? (I don't know if anyone's championing that.)

I am, sort of. And yes, this intersects with page types. My picture is that a page type identifies a template for a page, and the template includes the set of metadata items that may or must appear in it. And Yari can use the template in combination with the metadata to build page elements like spec tables, security requirements, property attributes, back/next links, and lots of other things that are currently done ad hoc using macros.

[Rumyra]

Thanks for starting the discussion @wbamberg !

I envisaged experimental, standards & deprecated could be (hopefully) powered by bcd.

A bit of my preamble: I think we need to be mindful of contributors and even if we can't keep things simple, at least make sure it's clearly defined. I see this as one of the end goals to page types (so we can enforce the template) and I appreciate having more page types than less - in the end we shouldn't be restricted on content we might want to create in the future, and/or should be flexible enough to stay open to changes in the web platform we might not envisage at the moment. I think if we bear this in mind with decisions that would be a good thing.

Also maybe approaching this from two different perspectives, we use reference docs at the starter for these decisions a lot - and rightly so, they for the most part conform to structure and would be made a lot easier to write with data automatically added (as its consistent) - but possibly bearing in mind pages with no/unique defined structure ('guides' come to mind) would also be beneficial - what data would be beneficial there?

I'm probably saying a lot of what is thought already, but worth adding none the less.

External data consumers have shown an interest in using this data point

I think this is really important - not only should we consider what's good for authors, but also what's useful for others consumer the data

[wbamberg]

Thanks for starting the discussion @wbamberg !

I envisaged experimental, standards & deprecated could be (hopefully) powered by bcd.

A bit of my preamble: I think we need to be mindful of contributors and even if we can't keep things simple, at least make sure it's clearly defined. I see this as one of the end goals to page types (so we can enforce the template) and I appreciate having more page types than less - in the end we shouldn't be restricted on content we might want to create in the future, and/or should be flexible enough to stay open to changes in the web platform we might not envisage at the moment. I think if we bear this in mind with decisions that would be a good thing.

Yes, I think templates for page types should not just be for Yari but also for people writing pages, acting as meta-docs for the things the pages may/must include.

Also maybe approaching this from two different perspectives, we use reference docs at the starter for these decisions a lot - and rightly so, they for the most part conform to structure and would be made a lot easier to write with data automatically added (as its consistent) - but possibly bearing in mind pages with no/unique defined structure ('guides' come to mind) would also be beneficial - what data would be beneficial there?

Yes, @teoli2003 mentions above, some way to express ordering seems like a piece of metadata specific to guides.

[Josh-Cena]

External data consumers have shown an interest in using this data point

About this though, does any consumer actually consume API metadata via Markdown front matter, instead of standalone JSON databases (a.k.a. BCD)?

[Elchi3]

I don't know if anyone does this yet. Information is programmatically more accessible in front matter than in prose I think. However, that doesn't yet provide an API to this information. It is a good step towards it, though, so that MDN or someone else can build on top of it later.

I also think the MDN authoring experience is a bit nicer when I'm asked to put the info within the same document in the front matter as opposed to somewhere else in a standalone JSON that I need to find and understand. (BCD that comes with its own tooling etc and is our exception here, I think).

So, I believe the reason we think about metadata in the front matter is that it's a better contribution experience than standalone data (which was tried previously with mdn/data and wasn't liked so much). I don't think this approach prevents future consumption of this data but I'm happy to hear thoughts about it.