require multiple BCD tables by specifying `browser-compat` as an array #20051

yin1999 · 2022-08-28T01:55:25Z

Summary

For we may going to deprecate Compat/Specifications macro parameters, we should
update the documentation about multiple BCD tables querying (for this feature has already been supported by mdn/yari#6465).

Metadata

Rewrites (or significantly expands) a document

github-actions · 2022-08-28T01:58:15Z

Preview URLs

/en-US/docs/MDN/Writing_guidelines/Page_structures/Compatibility_tables

(this comment was updated 2022-10-20 07:58:46.528096)

files/en-us/mdn/writing_guidelines/page_structures/compatibility_tables/index.md

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>

files/en-us/mdn/writing_guidelines/page_structures/compatibility_tables/index.md

wbamberg

I think that representing BCD for API pages is not this simple: see the previous discussion.

yin1999 · 2022-08-31T00:00:20Z

I think that representing BCD for API pages is not this simple: see the previous discussion.

Or should we use Property page (or other than API page) examples here (seems we haven't reached a consensus on API page)

bsmth · 2022-10-10T08:04:14Z

Hi @yin1999 @wbamberg - should we move this to a discussion? Does this syntax work or is it a feature request?

browser-compat:
  - api.MessageChannel
  - api.MessagePort

yin1999 · 2022-10-10T08:09:54Z

Hi @yin1999 @wbamberg - should we move this to a discussion? Does this syntax work or is it a feature request?
browser-compat:
  - api.MessageChannel
  - api.MessagePort

This actually works, the discussion about how to represent BCD for API pages blocked this.

bsmth · 2022-10-10T10:23:40Z

OK thanks. This PR adds a note describing how to add multiple BCD tables as array. Is there anything blocking this from landing in its current state? The discussion looks unrelated to the suggested changes.

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>

bsmth

Looks good to me 👍🏻

bsmth · 2022-10-17T08:43:11Z

@wbamberg would the example be better if we used something other than an API? A CSS feature, maybe?

wbamberg · 2022-10-18T20:34:02Z

I'm sorry to be unhelpful wrt this PR. It's not your fault, it's that we are IMO rather unclear about how we want to use the browser-compat front matter key in our pages.

I'm not really happy with pages randomly choosing to include multiple browser-compat queries.

Here's one reason: we use BCD to keep some other metadata items:

status things like "experimental", "deprecated"
the spec URL (actually this can be an array, but that's a different complaint)

At the moment, we manually represent things like "experimental", "deprecated" by adding macros like {{SeeCompatTable}} to the page, so the info is represented in two places and can (and does) get out of sync. I would like to be able to use the status metadata in BCD instead of these macros, so we only represent the info in one place. See mdn/yari#7227 for some work on this.

If there are multiple BCD queries, what am I to do here?

Similarly, I would like us to use the W3C's webref package to fetch the IDL for an interface, so I could use it for things like:

is the item available in workers?
does the item require a secure context?

Currently, again, both these things are represented manually, using macros.

I also think there's potential to use webref for things like building sidebars. And I think with work like this we could make MDN much more consistent, reliable, and maintainable.

But this kind of work is premised on being able to find out which spec an item is defined in. If we have multiple BCD queries, with multiple spec URLs, which one do I choose?

So all that doesn't necessarily mean we should never allow multiple BCD queries, but it does make me think we should have a more organized approach than "do what you want". Maybe some types of pages can have multiple queries and others can't, and we should say which are which. Maybe there are some conditions in which multiple tables are OK, and we have some other way to resolve the issues above.

It might be worth looking at the pages we currently have that define multiple BCD queries, and figure out patterns.

This is the complete set of pages that have >1 BCD query:

We can obviously see some patterns:

several Web/API overview pages, which reflects the problem we have representing BCD for Web APIs, as I referenced before (https://github.com/mdn/content/discussions/4920)
several CSS module pages, that want to list tables for all the items defined by that module (this is really the CSS equivalent of the Web/API overview page dilemma)
several HTML attribute pages, which reflects the ongoing question about whether we should separate attribute pages that apply to different elements (Project: HTML Attributes openwebdocs/project#114)
several random guide pages. I think there's a strong argument for not having browser-compat for guide pages, and instead having guide pages pass a BCD query argument to {{Compat}}.
...probably a few other tricky cases.

(Looking at these, I think multiple BCD queries is often a kind of "docs smell", like a code smell, a sign that there is some deeper problem that we are trying to hide.)

Perhaps we could try to resolve these, and come up with some guidelines that would enable people to represent the compat they want to, while still enabling the features I'm talking about here. I'd be happy to try to work through these.

But in the meantime I'm reluctant to document this just as "a thing you can do, if you feel like it".

bsmth · 2022-10-19T08:39:37Z

Thanks @wbamberg for the detailed response, I understand the concerns.

To summarize; adding multiple BCD entries as an array is technically possible, but is discouraged (or a possible anti-pattern). Documenting the ability to add multiple BCD entries will propagate this document structure.

If this is pending a decision and agreement for how to proceed, I suggest we close this PR and reference this in the existing discussion, do you have any objections?

wbamberg · 2022-10-19T17:07:40Z

Thanks @wbamberg for the detailed response, I understand the concerns.

To summarize; adding multiple BCD entries as an array is technically possible, but is discouraged (or a possible anti-pattern). Documenting the ability to add multiple BCD entries will propagate this document structure.

If this is pending a decision and agreement for how to proceed, I suggest we close this PR and reference this in the existing discussion, do you have any objections?

Thinking about this some more: as it stands this PR makes things better rather than worse. This page already recommends including multiple BCD queries for API overview pages sometimes:

API landing pages optionally have a browser compatibility section that shows compatibility tables for one or more of the most important interfaces in the API. If the compatibility is similar for most interfaces in the API then often just one compatibility table is needed. If compatibility across the API is complicated/impossible to capture in a few tables, this sections should be omitted.

To fill in the browser compatibility section, you may first need to create/update entries for the API interfaces in our Browser compat data repo — see our guide on how to do this.

Add the {{Compat("path.to.feature.Interface")}} macro for each interface for which compatibility information is required, replacing the "path.to.feature.Interface" argument with the path to the desired interface in the browser compatibility data.

This PR just documents a better way of doing that. So maybe we should just merge it, and have the conversation separately.

bsmth · 2022-10-20T07:55:26Z

This PR just documents a better way of doing that. So maybe we should just merge it, and have the conversation separately.

Thanks Will, I think that's a good call. I'm going to merge this one now, thanks @yin1999 for the additions 🙌🏻

require multiple BCD tables by specifying browser-compat as an array

b722311

yin1999 requested a review from a team as a code owner August 28, 2022 01:55

yin1999 requested review from bsmth and removed request for a team August 28, 2022 01:55

github-actions bot added the Content:Other Any docs not covered by another "Content:" label label Aug 28, 2022

yin1999 mentioned this pull request Aug 28, 2022

sync with english version for BCD tables guide mdn/translated-content#8057

Merged

Josh-Cena reviewed Aug 28, 2022

View reviewed changes

files/en-us/mdn/writing_guidelines/page_structures/compatibility_tables/index.md Outdated Show resolved Hide resolved

Josh-Cena reviewed Aug 28, 2022

View reviewed changes

files/en-us/mdn/writing_guidelines/page_structures/compatibility_tables/index.md Outdated Show resolved Hide resolved

Apply suggestions from code review

408b9eb

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>

Josh-Cena reviewed Aug 28, 2022

View reviewed changes

files/en-us/mdn/writing_guidelines/page_structures/compatibility_tables/index.md Outdated Show resolved Hide resolved

wbamberg reviewed Aug 29, 2022

View reviewed changes

yin1999 and others added 2 commits October 17, 2022 16:16

Apply suggestions from code review

5002734

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>

Merge branch 'main' into patch-1

d05414b

bsmth approved these changes Oct 17, 2022

View reviewed changes

wbamberg approved these changes Oct 19, 2022

View reviewed changes

Merge branch 'main' into patch-1

a2f3d12

bsmth merged commit ad8671a into mdn:main Oct 20, 2022

yin1999 deleted the patch-1 branch October 20, 2022 09:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

require multiple BCD tables by specifying `browser-compat` as an array #20051

require multiple BCD tables by specifying `browser-compat` as an array #20051

yin1999 commented Aug 28, 2022

github-actions bot commented Aug 28, 2022 •

edited

Loading

wbamberg left a comment •

edited

Loading

yin1999 commented Aug 31, 2022 •

edited

Loading

bsmth commented Oct 10, 2022

yin1999 commented Oct 10, 2022

bsmth commented Oct 10, 2022

bsmth left a comment

bsmth commented Oct 17, 2022

wbamberg commented Oct 18, 2022 •

edited

Loading

bsmth commented Oct 19, 2022

wbamberg commented Oct 19, 2022

bsmth commented Oct 20, 2022

require multiple BCD tables by specifying browser-compat as an array #20051

require multiple BCD tables by specifying browser-compat as an array #20051

Conversation

yin1999 commented Aug 28, 2022

Summary

Metadata

github-actions bot commented Aug 28, 2022 • edited Loading

wbamberg left a comment • edited Loading

Choose a reason for hiding this comment

yin1999 commented Aug 31, 2022 • edited Loading

bsmth commented Oct 10, 2022

yin1999 commented Oct 10, 2022

bsmth commented Oct 10, 2022

bsmth left a comment

Choose a reason for hiding this comment

bsmth commented Oct 17, 2022

wbamberg commented Oct 18, 2022 • edited Loading

bsmth commented Oct 19, 2022

wbamberg commented Oct 19, 2022

bsmth commented Oct 20, 2022

require multiple BCD tables by specifying `browser-compat` as an array #20051

require multiple BCD tables by specifying `browser-compat` as an array #20051

github-actions bot commented Aug 28, 2022 •

edited

Loading

wbamberg left a comment •

edited

Loading

yin1999 commented Aug 31, 2022 •

edited

Loading

wbamberg commented Oct 18, 2022 •

edited

Loading