Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add mdn_url value for theme-color meta name #6014

Merged
merged 1 commit into from
Apr 23, 2020

Conversation

sideshowbarker
Copy link
Collaborator

No description provided.

@ghost ghost added the data:html 📄 Compat data for HTML elements. https://developer.mozilla.org/docs/Web/HTML label Apr 20, 2020
@Elchi3
Copy link
Member

Elchi3 commented Apr 23, 2020

Thanks @sideshowbarker!
In terms of BCD, this is okay as is.

I wonder if we have agreement on page structures on MDN. So far, the HTML reference documentation has pages for HTML elements and maybe sometimes pages for attributes. You've decided to go deeper and create pages for more attributes and specific values. This might make sense, but I would like it to be discussed. Can you start a discussion on HTML docs page structure either in https://github.com/mdn/sprints or https://discourse.mozilla.org/c/mdn/236 ?
For a move of MDN content into structured markdown, we have thought quite a bit about page types, too, but I don't think these sub page have been considered so far. They could be, probably, so we should make a plan on structures and your input would be useful. (cc @wbamberg )

Copy link
Member

@Elchi3 Elchi3 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving and merging as these MDN pages exist at these URLs (for now).

@Elchi3 Elchi3 merged commit e601f9b into master Apr 23, 2020
@Elchi3 Elchi3 deleted the meta-name-theme-color-mdn-url branch April 23, 2020 14:17
@sideshowbarker
Copy link
Collaborator Author

sideshowbarker commented Apr 24, 2020

I wonder if we have agreement on page structures on MDN. So far, the HTML reference documentation has pages for HTML elements and maybe sometimes pages for attributes. You've decided to go deeper and create pages for more attributes and specific values. This might make sense, but I would like it to be discussed. Can you start a discussion on HTML docs page structure either in https://github.com/mdn/sprints or https://discourse.mozilla.org/c/mdn/236 ?

Will do.

But in short for now here, I want to mention: I don’t actually have a strong preference for how we structure MDN content for cases like this — but I do have a strong preference that we end up with a way in BCD that allows for every subfeature to be associated with its own spec URL.


Proposal

(I can copy this to a new issue later, but I want to mention at point-of-use here too)

If we were to start by:

  • first from the https://github.com/w3c/browser-compat-data fork take the already-identified-from-scraping-MDN spec_url values there, and put them into BCD upstream — as we have done already for all features and subfeatures in the BCD javascript subtree; and then also:
  • initiate a policy, going forward, to manually add spec_url values (over time, as we come across them, not necessarily all at once) to BCD for any (sub)features which we couldn’t get from that initial MDN scraping — and of course also when new (sub)features are added

…then we have a basis for handling cases like specific one I ran into here.


Longer explanation

While I’m confident the rewrite I did of the related MDN content in this case ended up being a real improvement to that content, I didn’t do it because I felt strongly that restructuring it into additional sub-articles was intrinsically better in and of itself — rather I did it in part as a workaround for the fact we haven’t yet agreed to start putting spec_url values for all features into BCD.

So after I raise a https://github.com/mdn/sprints issue for the MDN aspect of this, if the resolution there ends up being that for MDN we don’t want to structure content into sub-articles as deeply as I did for this case, then I will very happily go along with that — and will also be happy to take the sub-articles I spun out for this, and fold them back into a single MDN article, as we had before.

But if it turns out that way, we’ll still continue to have the root problem I was trying to work around.

The changes that’d actually help solve the root problem are what’s in the Proposal part above.


More details about the root problem

A big part of the reason I moved the MDN content for theme-color into a sub-article is this: The HTML spec needed an MDN annotation for theme-color, but basically the only way I currently have to make an MDN annotation actually show up for theme-color in the HTML spec is if theme-color in MDN has its own spec URL associated with it.

The same is true in general for all specs: For each place in a spec where we want to have an MDN annotation, there needs to be somewhere in BCD itself or in MDN that associates the corresponding BCD feature with its own spec URL.

However, without having spec_url values for all features in upstream BCD data directly, the only current way to identify the spec URLs needed is by scraping MDN articles to get them indirectly.

But in cases where one MDN article about a feature also documents multiple BCD subfeatures, MDN currently doesn’t provide the granularity necessary for associating each BCD subfeature inside the overall MDN article with that subfeature’s own spec URL. Instead we’re basically limited to having the Specifications table include just one spec URL for the parent BCD feature.

So, putting a feature into its own sub-article with its own Specifications table give us a way to directly associate that subfeature with its own spec URL.

Of course it’s imaginable we could put all spec URLs for all the subfeatures in an MDN article into that article’s Specifications table too — but I don’t think we’d want to do that in practice, because in some cases that means we end up with a dozen or whatever spec URLs in a Specifications table.

And even if did want to list a dozen spec URLs in one Specifications table, it still wouldn’t fix the root problem I was trying to work around — because for any given subfeature, that still wouldn’t provide any way to associate the spec URL for that subfeature with the specific subsection for that subfeature in the overall MDN article where that subfeature is included.

…hence why I’d really like to see us make the changes outlined in the Proposal part above.

@sideshowbarker
Copy link
Collaborator Author

Can you start a discussion on HTML docs page structure either in https://github.com/mdn/sprints or https://discourse.mozilla.org/c/mdn/236 ?

Raised https://github.com/mdn/sprints/issues/3158

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
data:html 📄 Compat data for HTML elements. https://developer.mozilla.org/docs/Web/HTML
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants