More guidance about examples

files/en-us/mdn/structures/code_examples/index.md

@@ -65,6 +65,51 @@ Optionally, you might want to show a static image of the code's resulting output
 
 Traditional live samples are inserted into the page using the [`EmbedLiveSample`](https://github.com/mdn/yari/blob/main/kumascript/macros/EmbedLiveSample.ejs) macro. An \\{{EmbedLiveSample}} call dynamically grabs the code blocks in the same document section as itself and puts them into a document, which it then inserts into the page inside an {{htmlelement("iframe")}}. See our [Live samples guide](/en-US/docs/MDN/Structures/Live_samples) for more information.
 
+### Formatting live samples
+
+If you write a live sample in the "Examples" section, provide a descriptive H3 heading for this live sample example. Ideally, write a short description of the example explaining the scenario and what you are hoping to demonstrate. Then add subsections with following H4 headings, in the order listed:
+
+- HTML
+- CSS
+- JavaScript
+- Result
+Write the code blocks in the respective subsections listed above.
+In the **Result** subsection, add the call to the [`EmbedLiveSample` macro](/en-US/docs/MDN/Structures/Live_samples#live_sample_macros). Preferably, include some more prose in this subsection to describe the result.
+If you're not using a particular language type (for example, if you are not using JavaScript) or if you are hiding it, then you should omit the corresponding heading.
+
+For example:
+
+````
+## Examples
+
+### Styling a paragraph
+
+In this example, we're using CSS to style paragraphs that have the `fancy` class set.
+
+#### HTML
+
+```html
+<p>I'm not fancy.</p>
+
+<p class="fancy">But I am!</p>
+```
+
+#### CSS
+
+```css
+p.fancy {
+  color: red;
+}
+```
+
+#### Result
+
+\{{EmbedLiveSample("Styling a paragraph")}}
+
+Only the `<p>` element with `class="fancy"` will get styled `red`.
+
+````
+
 ## GitHub live samples
 
 GitHub live samples are inserted into the page using the [`EmbedGHLiveSample`](https://github.com/mdn/yari/blob/main/kumascript/macros/EmbedGHLiveSample.ejs) macro. An \\{{EmbedGHLiveSample}} call dynamically grabs the document at a specified URL (which has to be inside the **mdn** GitHub organization), and inserts into the page inside an {{htmlelement("iframe")}}.

files/en-us/mdn/structures/page_types/api_constructor_subpage_template/index.md

@@ -113,17 +113,33 @@ This is normally just "An instance of the {{domxref("NameOfTheParentInterface")}
 
 ## Examples
 
-Fill in a simple example that nicely shows a typical usage of the constructor, then perhaps some more complex examples (see our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information).
+### A descriptive heading
 
-```js
-my code block
-```
+Each example must have an H3 heading naming the example. The heading should be descriptive of what the example is doing. For example, "A simple example" does not say anything about the example and therefore, not a good heading. The heading should be concise. For a longer description, use the paragraph after the heading.
 
-And/or include a list of links to useful code samples that live elsewhere:
+See our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information.
 
-- x
-- y
-- z
+> **Note:** Sometimes you will want to link to examples given on another page.
+>
+> If you have some examples in this page and some more examples on another page, then include an H3 heading for each example in this page, then a final H3 heading with the text "More examples", under which you can link to the extra examples. For example:
+>
+>  ```md
+>  ## Examples
+>
+>  ### Using the fetch API
+>  ... example of Fetch
+>
+>  ### More examples
+>  ...links to further examples
+>  ```
+>
+> If you _only_ have examples on another page, then you should not provide any H3 headings, but just add the links directly under the "Examples" H2. For example:
+>
+>  ```md
+>   ## Examples
+>
+>   For examples of this API, see [the page on fetch()](https://example.org).
+>
 
 ## Specifications
 

files/en-us/mdn/structures/page_types/api_event_subpage_template/index.md

@@ -142,17 +142,11 @@ which can provide more information.
 
 ## Examples
 
-Fill in a simple example that nicely shows a typical usage of the event, then perhaps some more complex examples (see our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information). You should show how to use the event with both, {{domxref("EventTarget.addEventListener", "addEventListener()")}} and with the event handler property.
+### A descriptive heading
 
-```js
-my code block
-```
-
-And/or include a list of links to useful code samples that live elsewhere:
+Each example must have an H3 heading naming the example. The heading should be descriptive of what the example is doing. For example, "A simple example" does not say anything about the example and therefore, not a good heading. The heading should be concise. For a longer description, use the paragraph after the heading.
 
-- x
-- y
-- z
+See our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information.
 
 ## Specifications
 

files/en-us/mdn/structures/page_types/api_landing_page_template/index.md

@@ -133,21 +133,11 @@ The _name of interface_ extends the following APIs, adding the listed features.
 
 ## Examples
 
-Fill in a simple example that nicely shows a typical usage of the API, then perhaps some more complex examples (see our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information).
+### A descriptive heading
 
-This text should be replaced with a brief description of what the example demonstrates.
+Each example must have an H3 heading naming the example. The heading should be descriptive of what the example is doing. For example, "A simple example" does not say anything about the example and therefore, not a good heading. The heading should be concise. For a longer description, use the paragraph after the heading.
 
-```js
-my code block
-```
-
-If you've included an example directly in the page as shown above, and that example is longer than 4-5 lines or so, consider following the example with a step-by-step explanation of what it's doing, so that new programmers can learn more easily, and to help smooth the learning curve for complicated subjects.
-
-And/or include a list of links to useful code samples that live elsewhere:
-
-- x
-- y
-- z
+See our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information.
 
 ## Specifications
 

files/en-us/mdn/structures/page_types/api_method_subpage_template/index.md

@@ -104,7 +104,7 @@ Fill in a syntax box, according to the guidance in our [syntax sections](/en-US/
 
 Include a description of the method's return value, including data type and what it represents.
 
-If the method doesn't return anything, just put "None {{jsxref('undefined')}}.".
+If the method doesn't return anything, just put "None ({{jsxref('undefined')}}).".
 
 ### Exceptions
 
@@ -127,17 +127,13 @@ Here is an example where a method can raise a `DOMException` with a name of `Ind
 - {{jsxref("TypeError")}}
   - : Thrown …
 
-Fill in a simple example that nicely shows a typical usage of the method, then perhaps some more complex examples (see our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information).
+## Examples
 
-```js
-my code block
-```
+### A descriptive heading
 
-And/or include a list of links to useful code samples that live elsewhere:
+Each example must have an H3 heading naming the example. The heading should be descriptive of what the example is doing. For example, "A simple example" does not say anything about the example and therefore, not a good heading. The heading should be concise. For a longer description, use the paragraph after the heading.
 
-- x
-- y
-- z
+See our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information.
 
 ## Specifications
 

files/en-us/mdn/structures/page_types/api_property_subpage_template/index.md

@@ -93,17 +93,11 @@ Include a description of the property's value, including data type and what it r
 
 ## Examples
 
-Fill in a simple example that nicely shows a typical usage of the property, then perhaps some more complex examples (see our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information).
+### A descriptive heading
 
-```js
-my code block
-```
+Each example must have an H3 heading naming the example. The heading should be descriptive of what the example is doing. For example, "A simple example" does not say anything about the example and therefore, not a good heading. The heading should be concise. For a longer description, use the paragraph after the heading.
 
-And/or include a list of links to useful code samples that live elsewhere:
-
-- x
-- y
-- z
+See our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information.
 
 ## Specifications
 

files/en-us/mdn/structures/page_types/api_reference_page_template/index.md

@@ -102,17 +102,12 @@ Listen to these events using [`addEventListener()`](/en-US/docs/Web/API/EventTar
 
 ## Examples
 
-Fill in a simple example that nicely shows a typical usage of the interfaces, then perhaps some more complex examples (see our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information).
+### A descriptive heading
 
-```js
-my code block
-```
+Each example must have an H3 heading naming the example. The heading should be descriptive of what the example is doing. For example, "A simple example" does not say anything about the example and therefore, not a good heading. The heading should be concise. For a longer description, use the paragraph after the heading.
 
-And/or include a list of links to useful code samples that live elsewhere:
+See our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information.
 
-- x
-- y
-- z
 
 ## Specifications
 

files/en-us/mdn/structures/page_types/aria_page_template/index.md

@@ -72,17 +72,11 @@ Include a complete description of the attribute or role.
 
 ## Examples
 
-Fill in a simple example that shows a typical usage of the property, then perhaps some more complex examples. For more information, see our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples).
+### A descriptive heading
 
-```html
-my code block
-```
-
-And/or include a list of links to useful code samples that live elsewhere:
+Each example must have an H3 heading naming the example. The heading should be descriptive of what the example is doing. For example, "A simple example" does not say anything about the example and therefore, not a good heading. The heading should be concise. For a longer description, use the paragraph after the heading.
 
-- x
-- y
-- z
+See our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information.
 
 ## Accessibility concerns
 

files/en-us/mdn/structures/page_types/css_property_page_template/index.md

@@ -110,17 +110,11 @@ Include a description of the property and what component subvalues make up a com
 
 ## Examples
 
-Fill in a simple example that nicely shows a typical usage of the property, then perhaps some more complex examples (see our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information).
+### A descriptive heading
 
-```css
-my code block
-```
-
-And/or include a list of links to useful code samples that live elsewhere:
+Each example must have an H3 heading naming the example. The heading should be descriptive of what the example is doing. For example, "A simple example" does not say anything about the example and therefore, not a good heading. The heading should be concise. For a longer description, use the paragraph after the heading.
 
-- x
-- y
-- z
+See our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information.
 
 ## Accessibility concerns
 

files/en-us/mdn/structures/page_types/css_selector_page_template/index.md

@@ -93,17 +93,11 @@ The summary paragraph — start by naming the selector and saying what it does.
 
 ## Examples
 
-Fill in a simple example that nicely shows a typical usage of the selector, then perhaps some more complex examples (see our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information).
+### A descriptive heading
 
-```css
-my code block
-```
-
-And/or include a list of links to useful code samples that live elsewhere:
+Each example must have an H3 heading naming the example. The heading should be descriptive of what the example is doing. For example, "A simple example" does not say anything about the example and therefore, not a good heading. The heading should be concise. For a longer description, use the paragraph after the heading.
 
-- x
-- y
-- z
+See our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information.
 
 ## Accessibility concerns
 

files/en-us/mdn/structures/page_types/html_element_page_template/index.md

@@ -107,17 +107,11 @@ Include a table of the events fired on this type of element, if any.
 
 ## Examples
 
-Fill in a simple example that nicely shows a typical usage of the element, then perhaps some more complex examples (see our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information).
+### A descriptive heading
 
-```html
-my code block
-```
+Each example must have an H3 heading naming the example. The heading should be descriptive of what the example is doing. For example, "A simple example" does not say anything about the example and therefore, not a good heading. The heading should be concise. For a longer description, use the paragraph after the heading.
 
-And/or include a list of links to useful code samples that live elsewhere:
-
-- x
-- y
-- z
+See our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information.
 
 ## Accessibility concerns
 

files/en-us/mdn/structures/page_types/http_header_page_template/index.md

@@ -125,17 +125,11 @@ If the header has a lot of available directives, feel free to include multiple d
 
 ## Examples
 
-Fill in a some examples that show common use cases of the HTTP header (for example, a typical request and response sequence).
+### A descriptive heading
 
-```http
-my HTTP header example
-```
-
-And/or include a list of links to useful code samples that live elsewhere:
+Each example must have an H3 heading naming the example. The heading should be descriptive of what the example is doing. For example, "A simple example" does not say anything about the example and therefore, not a good heading. The heading should be concise. For a longer description, use the paragraph after the heading.
 
-- x
-- y
-- z
+See our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information.
 
 ## Specifications
 

files/en-us/mdn/structures/page_types/svg_element_page_template/index.md

@@ -111,17 +111,11 @@ This element implements the {{domxref("NameOfSVGDOMElement")}} interface.
 
 ## Examples
 
-Fill in a simple example that nicely shows a typical usage of the element, then perhaps some more complex examples (see our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information).
+### A descriptive heading
 
-```svg
-my code block
-```
+Each example must have an H3 heading naming the example. The heading should be descriptive of what the example is doing. For example, "A simple example" does not say anything about the example and therefore, not a good heading. The heading should be concise. For a longer description, use the paragraph after the heading.
 
-And/or include a list of links to useful code samples that live elsewhere:
-
-- x
-- y
-- z
+See our guide on how to add [code examples](/en-US/docs/MDN/Structures/Code_examples) for more information.
 
 ## Specifications