Fix up MDN API landing page template for browser-compat #5225

hamishwillee · 2021-05-24T00:27:16Z

The new way of doing browser compatibility sections is to list the BCD path in the page frontmatter browser-compat key and just use {{Compat}} as a placeholder. Also we no longer have hidden sections.

This fixes just one template: https://developer.mozilla.org/en-US/docs/MDN/Structures/Page_types/API_landing_page_template. If this is merged I'll do the other MDN instructional docs/templates - e.g. https://developer.mozilla.org/en-US/docs/MDN/Structures/Page_types/SVG_element_page_template

This follows follows on naturally from #4398 and #2228

@wbamberg @Elchi3 Sanity check would be good :-)

github-actions · 2021-05-24T00:29:22Z

Preview URLs

Flaws

Note! 2 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/MDN/Structures/Page_types/API_reference_page_template
Title: API reference page template
on GitHub
Flaw count: 10

macros:
- /en-us/docs/web/api/mdn (url: /en-US/docs/Web/API/MDN) does not exist
- /en-US/docs/Web/API/NameOfTheInterface/NameOfTheInterface does not exist
- /en-US/docs/Web/API/NameOfTheInterface does not exist
- /en-US/docs/Web/API/NameOfParentInterface does not exist
- /en-US/docs/Web/API/NameOfTheInterface/property1 does not exist
- and 4 more flaws omitted
bad_bcd_queries:
- No BCD data for query: path.to.feature.NameOfTheInterface

URL: /en-US/docs/MDN/Structures/Page_types/API_method_subpage_template
Title: API method subpage template
on GitHub
Flaw count: 2

macros:
- /en-us/docs/web/api/mdn (url: /en-US/docs/Web/API/MDN) does not exist
bad_bcd_queries:
- No BCD data for query: path.to.feature.NameOfTheMethod

URL: /en-US/docs/MDN/Structures/Page_types/API_landing_page_template
Title: API landing page template
on GitHub
Flaw count: 6

macros:
- /en-us/docs/web/api/mdn (url: /en-US/docs/Web/API/MDN) does not exist
- /en-US/docs/Web/API/NameOfTheInterface does not exist
- /en-US/docs/Web/API/Addition1 does not exist
- /en-US/docs/Web/API/Addition1 does not exist
bad_bcd_queries:
- No BCD data for query: path.to.feature.Interface_1
- No BCD data for query: path.to.feature.Interface_2

External URLs

URL: /en-US/docs/Web/API/AbortController
Title: AbortController
on GitHub

No new external URLs

URL: /en-US/docs/MDN/Structures/Page_types/API_reference_page_template
Title: API reference page template
on GitHub

No new external URLs

URL: /en-US/docs/MDN/Structures/Page_types/API_method_subpage_template
Title: API method subpage template
on GitHub

No new external URLs

URL: /en-US/docs/MDN/Structures/Page_types/API_landing_page_template
Title: API landing page template
on GitHub

No new external URLs

URL: /en-US/docs/MDN/Structures/Compatibility_tables
Title: Compatibility tables and the browser compatibility data repository (BCD)
on GitHub

No new external URLs

(this comment was updated 2021-06-04 06:57:45.443805)

wbamberg · 2021-05-24T03:58:53Z

Thanks for doing this @hamishwillee ! Definitely needed, and this general update looks fine. Having said that, I'm not actually sure yet whether we will be doing this for API pages in particular. See https://github.com/mdn/content/discussions/4920.

What you've written here definitely applies for https://developer.mozilla.org/en-US/docs/MDN/Structures/Page_types#css_feature_reference_page and very likely:

https://developer.mozilla.org/en-US/docs/MDN/Structures/Page_types#api_reference_subpage
https://developer.mozilla.org/en-US/docs/MDN/Structures/Page_types#html_element_reference_page
https://developer.mozilla.org/en-US/docs/MDN/Structures/Page_types#svg_element_reference_page
https://developer.mozilla.org/en-US/docs/MDN/Structures/Page_types#http_header_reference_page

...and of course JS, which does not seem to be documented here...

This update could also talk about using the {{Specifications}} macro, instead of a handwritten table.

hamishwillee · 2021-05-25T03:47:27Z

Hi @wbamberg, Thank you for the feedback. IMO there isn't any reason not to roll this out to API docs and everywhere else. Even if we are sporadic about roll out, the howto docs should reflect a consistent approach.

I will add update for {{Specifications}} too. Originally I decided not to because these are not as well rolled out. But then I realised that's not the point as this is for new docs, and the update to BCD needs to include this information going forward.

hamishwillee · 2021-05-25T06:57:17Z

@wbamberg et al, OK I did a further update to add info on how to update the specifications table.

That lead me to wondering how you update the spec_url, which lead to me updating https://developer.mozilla.org/en-US/docs/MDN/Structures/Compatibility_tables with:

basic information on how to find the spec URL
Fixes to update from pointing to git main branch rather than master
Updated AbortController as an example (it is a better example than the other two as it has both the spec and browser compat.

Anyway, needs a re-review before I go and roll everything out everywhere :-)

files/en-us/mdn/structures/compatibility_tables/index.html

Elchi3

Thanks for updating this!

files/en-us/mdn/structures/compatibility_tables/index.html

wbamberg · 2021-05-26T03:27:25Z

Hi @wbamberg, Thank you for the feedback. IMO there isn't any reason not to roll this out to API docs and everywhere else.

For API landing pages specifically, it's not at all obvious to me that the approach of adding a single BCD query into front matter makes sense, because the tech covered by a single API landing page doesn't correspond to a single BCD query. For example, which single query would you use to describe the compat status of the WebRTC API: https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API ?

hamishwillee · 2021-05-28T06:22:05Z

@wbamberg @Elchi3

Re #5225 (comment) "For API landing pages specifically, it's not at all obvious ..."

OK, I get you. Part of the problem is that it is not all that clear in the original doc. At the moment it talks about just one compat table. What I think this should say is that you may find it useful to display BCD tables for the main interfaces in an API - so work out the keys for each of them and put them in compatibility section using separate compat macro (or something similar). Does that make sense? For now I have just reverted that section.

If so, what about specifications? That macro does not take a BCD entry. So do we say "create your own table" or do I remove this section, or what?

FURTHER ...
I have updated the API reference and API reference method pages, because those actually can use the compat and specification macros. As part of that I reworked the top note to better highlight frontmatter. IMO this is much cleaner.

Changes requested done.

Elchi3 · 2021-05-31T15:19:15Z

files/en-us/mdn/structures/compatibility_tables/index.html

+
+<p>The compatibility and specification tables corresponding to the key are then automatically rendered in place of the <code>\{{Compat}}</code> and <code>\{{Specifications}}</code> macros in the source.</p>
+
+<p>You can also specify the desired API as the first argument to the macro as shown: <code>\{{Compat("api.AbortController")}}</code>. This can be useful if multiple compatibility tables are required on the same page.</p>


fwiw, this is also true for specification tables, see https://github.com/mdn/yari/blob/main/kumascript/macros/Specifications.ejs

Thanks @Elchi3. I did test that and it didn't work. Must have made a mistake. Will try again.

Elchi3 · 2021-05-31T15:24:54Z

If so, what about specifications? That macro does not take a BCD entry. So do we say "create your own table" or do I remove this section, or what?

The specification macro can actually take a BCD query if needed. I think having a manual spec table is fine as the exception, too, though. I mean it is just links to specs really. If certain pages need something more fancy, then I would decide on a case by case basis. The majority of reference-type pages should be fine with just {{Specifications}} imo.

hamishwillee · 2021-06-01T00:37:08Z

If so, what about specifications? That macro does not take a BCD entry. So do we say "create your own table" or do I remove this section, or what?

The specification macro can actually take a BCD query if needed. I think having a manual spec table is fine as the exception, too, though. I mean it is just links to specs really. If certain pages need something more fancy, then I would decide on a case by case basis. The majority of reference-type pages should be fine with just {{Specifications}} imo.

Great news. I did test this, which is why I thought it did not work. Will retest and update appropriately.

typo

Co-authored-by: Florian Scholz <[email protected]> Update files/en-us/mdn/structures/compatibility_tables/index.html Co-authored-by: Florian Scholz <[email protected]> Update files/en-us/mdn/structures/compatibility_tables/index.html Co-authored-by: Florian Scholz <[email protected]> Update files/en-us/mdn/structures/compatibility_tables/index.html Co-authored-by: Florian Scholz <[email protected]> Update files/en-us/mdn/structures/compatibility_tables/index.html Co-authored-by: Florian Scholz <[email protected]>

hamishwillee · 2021-06-04T06:58:56Z

@Elchi3 I've rebased to master and modified the API Landing page to improve the browser compat and specifications sections as discussed. It now says

Both these sections are optional
They can have multiple tables or none. Do what is sensible for the API.

Can you please review and (ideally) merge. After I'll roll out more broadly.

Elchi3

Awesome, thanks Hamish!

hamishwillee requested a review from a team as a code owner May 24, 2021 00:27

hamishwillee requested review from Elchi3 and removed request for a team May 24, 2021 00:27

hamishwillee changed the title ~~Fix up MDN instructions and templates for browser-compat~~ Fix up MDN API landing page template for browser-compat May 24, 2021

hamishwillee requested a review from a team as a code owner May 25, 2021 06:52

hamishwillee commented May 25, 2021

View reviewed changes

files/en-us/mdn/structures/compatibility_tables/index.html Show resolved Hide resolved

hamishwillee commented May 25, 2021

View reviewed changes

files/en-us/mdn/structures/compatibility_tables/index.html Show resolved Hide resolved

Elchi3 previously requested changes May 25, 2021

View reviewed changes

Elchi3 reviewed May 31, 2021

View reviewed changes

teoli2003 mentioned this pull request Jun 1, 2021

Put browser-compat info in front-runner everywhere on MDN openwebdocs/project#36

Closed

51 tasks

hamishwillee force-pushed the page_template_bcd branch from ba55aba to c3d2e83 Compare June 4, 2021 06:53

hamishwillee and others added 10 commits June 4, 2021 16:55

API landing page template: Fix compat

fba2c91

typo

Update with Specifications macro

fa65864

Fix up master to main in the compatibility table info

8f91536

Fix up AbortController - better example

b2f5b7b

Update instructions on how to work with compatibility tables

52f54af

minor fixes to api landing page

a693cc2

Method_subpage_mimimal

6d04ada

Updated guide pattern for api method subpage

5b66681

Add API reference page template

43fb6ec

hamishwillee added 2 commits June 4, 2021 16:55

Update/partially revert landing page

5dd45b1

Api landing - clarify that multiple specs/compat might be needed

cf67170

hamishwillee force-pushed the page_template_bcd branch from c3d2e83 to cf67170 Compare June 4, 2021 06:56

Elchi3 approved these changes Jun 4, 2021

View reviewed changes

Elchi3 merged commit 03feb1e into mdn:main Jun 4, 2021

hamishwillee deleted the page_template_bcd branch June 7, 2021 01:12

hamishwillee mentioned this pull request Jun 8, 2021

MDN API page templates for browser-compat pt 2 #5780

Merged

github-actions bot locked as resolved and limited conversation to collaborators Aug 7, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix up MDN API landing page template for browser-compat #5225

Fix up MDN API landing page template for browser-compat #5225

hamishwillee commented May 24, 2021

github-actions bot commented May 24, 2021 •

edited

Loading

wbamberg commented May 24, 2021

hamishwillee commented May 25, 2021

hamishwillee commented May 25, 2021

Elchi3 left a comment

wbamberg commented May 26, 2021

hamishwillee commented May 28, 2021

Elchi3 May 31, 2021

hamishwillee Jun 1, 2021

Elchi3 commented May 31, 2021

hamishwillee commented Jun 1, 2021

hamishwillee commented Jun 4, 2021

Elchi3 left a comment


		<p>The compatibility and specification tables corresponding to the key are then automatically rendered in place of the <code>\{{Compat}}</code> and <code>\{{Specifications}}</code> macros in the source.</p>

		<p>You can also specify the desired API as the first argument to the macro as shown: <code>\{{Compat("api.AbortController")}}</code>. This can be useful if multiple compatibility tables are required on the same page.</p>

Fix up MDN API landing page template for browser-compat #5225

Fix up MDN API landing page template for browser-compat #5225

Conversation

hamishwillee commented May 24, 2021

github-actions bot commented May 24, 2021 • edited Loading

Preview URLs

Flaws

External URLs

wbamberg commented May 24, 2021

hamishwillee commented May 25, 2021

hamishwillee commented May 25, 2021

Elchi3 left a comment

Choose a reason for hiding this comment

wbamberg commented May 26, 2021

hamishwillee commented May 28, 2021

Elchi3 May 31, 2021

Choose a reason for hiding this comment

hamishwillee Jun 1, 2021

Choose a reason for hiding this comment

Elchi3 commented May 31, 2021

hamishwillee commented Jun 1, 2021

hamishwillee commented Jun 4, 2021

Elchi3 left a comment

Choose a reason for hiding this comment

github-actions bot commented May 24, 2021 •

edited

Loading