More guidance about examples

[wbamberg]

@dipikabh , @teoli2003 , here's an attempt to update the meta-docs to be more prescriptive about examples.

In particular, I want to:

• require a descriptive heading for each example
• require a consistent organization for live samples

I removed the bit about linking to examples that live elsewhere, but maybe should put it back as it is probably legitimate sometimes. But I'm not sure how to work that into this structure. An H3 ### More examples? But what if there are only examples that live elsewhere?

Maybe:

• if there are only linked examples, put them right under ## Examples, with no H3s
• if there are some in-page examples and some linked ones, put the linked ones last, under an H3 ### More examples

?

[github-actions]

Preview URLs

• https://pr15894.content.dev.mdn.mozit.cloud/en-US/docs/MDN/Structures/Code_examples
• https://pr15894.content.dev.mdn.mozit.cloud/en-US/docs/MDN/Structures/Page_types/API_constructor_subpage_template
• https://pr15894.content.dev.mdn.mozit.cloud/en-US/docs/MDN/Structures/Page_types/API_event_subpage_template
• https://pr15894.content.dev.mdn.mozit.cloud/en-US/docs/MDN/Structures/Page_types/API_landing_page_template
• https://pr15894.content.dev.mdn.mozit.cloud/en-US/docs/MDN/Structures/Page_types/API_method_subpage_template
• https://pr15894.content.dev.mdn.mozit.cloud/en-US/docs/MDN/Structures/Page_types/API_property_subpage_template
• https://pr15894.content.dev.mdn.mozit.cloud/en-US/docs/MDN/Structures/Page_types/API_reference_page_template
• https://pr15894.content.dev.mdn.mozit.cloud/en-US/docs/MDN/Structures/Page_types/ARIA_Page_Template
• https://pr15894.content.dev.mdn.mozit.cloud/en-US/docs/MDN/Structures/Page_types/CSS_property_page_template
• https://pr15894.content.dev.mdn.mozit.cloud/en-US/docs/MDN/Structures/Page_types/CSS_selector_page_template
• https://pr15894.content.dev.mdn.mozit.cloud/en-US/docs/MDN/Structures/Page_types/HTML_element_page_template
• https://pr15894.content.dev.mdn.mozit.cloud/en-US/docs/MDN/Structures/Page_types/HTTP_header_page_template
• https://pr15894.content.dev.mdn.mozit.cloud/en-US/docs/MDN/Structures/Page_types/SVG_element_page_template

Flaws

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

URL: /en-US/docs/MDN/Structures/Page_types/HTML_element_page_template
Title: HTML element page template
on GitHub
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: path.to.feature.NameOfTheElement

---

URL: /en-US/docs/MDN/Structures/Page_types/API_property_subpage_template
Title: API property 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.NameOfTheProperty

---

URL: /en-US/docs/MDN/Structures/Page_types/CSS_property_page_template
Title: CSS property page template
on GitHub
Flaw count: 3

• macros:
  • /en-US/docs/Web/CSS/subvalue1 does not exist
  • /en-US/docs/Web/CSS/subvalue2 does not exist
• bad_bcd_queries:
  • No BCD data for query: css.properties.NameOfTheProperty

---

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_event_subpage_template
Title: API event 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.NameOfTheEvent_event

---

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

• 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
• sectioning:
  • Excess <h3> tag that is NOT at root-level (id='top_macros', text='Top macros')

---

URL: /en-US/docs/MDN/Structures/Page_types/HTTP_header_page_template
Title: HTTP header page template
on GitHub
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: path.to.feature.NameOfTheHeader

---

URL: /en-US/docs/MDN/Structures/Page_types/CSS_selector_page_template
Title: CSS selector page template
on GitHub
Flaw count: 1

• bad_bcd_queries:
  • No BCD data for query: css.selectors.NameOfTheSelector

---

URL: /en-US/docs/MDN/Structures/Page_types/API_constructor_subpage_template
Title: API constructor subpage template
on GitHub
Flaw count: 3

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

---

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

---

URL: /en-US/docs/MDN/Structures/Page_types/SVG_element_page_template
Title: SVG element page template
on GitHub
Flaw count: 2

• macros:
  • /en-US/docs/Web/API/NameOfSVGDOMElement does not exist
• bad_bcd_queries:
  • No BCD data for query: path.to.feature.NameOfTheElement

External URLs

URL: /en-US/docs/MDN/Structures/Page_types/HTML_element_page_template
Title: HTML element page template
on GitHub

No new external URLs

---

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

No new external URLs

---

URL: /en-US/docs/MDN/Structures/Page_types/CSS_property_page_template
Title: CSS property 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_event_subpage_template
Title: API event subpage template
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/ARIA_Page_Template
Title: ARIA page template
on GitHub

• https://w3c.github.io/aria-practices/ (1 time) (Note! This may be a new URL 👀)
• https://w3c.github.io/aria/ (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/MDN/Structures/Page_types/HTTP_header_page_template
Title: HTTP header page template
on GitHub

No new external URLs

---

URL: /en-US/docs/MDN/Structures/Page_types/CSS_selector_page_template
Title: CSS selector page template
on GitHub

No new external URLs

---

URL: /en-US/docs/MDN/Structures/Page_types/API_constructor_subpage_template
Title: API constructor 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/Page_types/SVG_element_page_template
Title: SVG element page template
on GitHub

No new external URLs

---

URL: /en-US/docs/MDN/Structures/Code_examples
Title: Code examples
on GitHub

No new external URLs

(this comment was updated 2022-06-14 04:36:25.009077)

[dipikabh]

Thank you for opening this much required PR, @wbamberg! Apologies for not looking at it sooner.
I'll get to it now.
(I am also much delayed in making a formal 'H3s in TOC' proposal)

[dipikabh]

I removed the bit about linking to examples that live elsewhere, but maybe should put it back as it is probably legitimate sometimes. But I'm not sure how to work that into this structure. An H3 ### More examples? But what if there are only examples that live elsewhere?

Maybe:

* if there are only linked examples, put them right under `## Examples`, with no H3s

* if there are some in-page examples and some linked ones, put the linked ones last, under an H3 `### More examples`

I like your proposal @wbamberg in those two scenarios for linking to other examples.

[wbamberg]

Thanks for your review, @dipikabh ! I have had a go at writing up rules for linking to external examples. For the time being I've only updated one page: https://pr15894.content.dev.mdn.mozit.cloud/en-US/docs/MDN/Structures/Page_types/API_constructor_subpage_template#examples thinking that once we are both happy with those words I can copy it to the other templates.

[teoli2003]

1 nit (at several places) and I think it is good to go.

(Approving as these are optional nits)

[dipikabh]

Thanks for the fixes, @wbamberg and for adding content for external examples!!
I've added my suggestions for linking to external examples bit.

[dipikabh]

I guess @wbamberg wanted to copy the 'external examples' note in other template pages. Guess he'll open a new PR when he's back. We can close this for now. Thanks for the fixes, @teoli2003!