fix(docs): add a page describing everything about feature statuses (#…

…31941)

* fix(docs): add a page describing everyging about standardization statuses

* Apply suggestions from code review

Co-authored-by: Brian Thomas Smith <[email protected]>

* standardization->technology

* Apply suggestions from code review

Co-authored-by: Brian Thomas Smith <[email protected]>

* address review comments

* fix flaws

* Apply suggestions from code review

Co-authored-by: Brian Thomas Smith <[email protected]>

* address review comments

* rename to 'feature status'

* Apply suggestions from code review

Co-authored-by: Hamish Willee <[email protected]>

* make separate sections in all the templates

* Update files/en-us/mdn/writing_guidelines/page_structures/banners_and_notices/index.md

Co-authored-by: wbamberg <[email protected]>

* Apply suggestions from code review

Co-authored-by: wbamberg <[email protected]>

* address review comments

* address review comments

* Update files/en-us/mdn/writing_guidelines/page_structures/banners_and_notices/index.md

* Apply suggestions from code review

Co-authored-by: Hamish Willee <[email protected]>

* address review comments

* Apply suggestions from code review

Co-authored-by: Hamish Willee <[email protected]>

* Update banners and notices

* cover the case of multiple 'browser-compat' values

---------

Co-authored-by: Brian Thomas Smith <[email protected]>
Co-authored-by: Hamish Willee <[email protected]>
Co-authored-by: wbamberg <[email protected]>

files/en-us/mdn/writing_guidelines/experimental_deprecated_obsolete/index.md

@@ -20,7 +20,7 @@ For a technology marked **experimental**, one or more of the following condition
 - It is only supported through configuration changes such as preferences or flags, regardless of the number of supported rendering engines.
 - Its defining specification is likely to change significantly in backwards-incompatible ways (i.e., it may break existing code that relies on the feature).
 
-> **Note:** A feature that is only released on one rendering engine is still considered experimental even if it is available on preview builds of other rendering engines (or by setting a preference or flag).
+> **Note:** A feature released only on one rendering engine is still considered experimental even if it is available on preview builds of other rendering engines (or by setting a preference or flag).
 
 The **experimental** status of a technology may expire if one or more of the following conditions is met:
 
@@ -72,14 +72,7 @@ If the item was _never_ implemented in a release version of _any_ browser, not e
 
 If the item was implemented in any release version of any one or more browsers but _only_ behind a preference or a flag, do not delete the item from the documentation immediately. Instead, mark the item as **deprecated** as follows:
 
-- If the item has any documentation pages describing only that one item (such as {{domxref("RTCPeerConnection.close()")}}), add the [`deprecated_header`](https://github.com/mdn/yari/blob/main/kumascript/macros/Deprecated_Header.ejs) macro to the top of the page and add the following `status:` front-matter entry:
-
-  ```yaml
-  status:
-    - deprecated
-  ```
-
-- On the overview page for the element, interface, or API, find the list of items that includes the item that's been removed from the specification and add the [`deprecated_inline`](https://github.com/mdn/yari/blob/main/kumascript/macros/Deprecated_Inline.ejs) macro after the item's name in that list.
+- Update the item's status data in the browser-compat-data repository by [submitting a pull request](https://github.com/mdn/browser-compat-data/blob/main/docs/contributing.md#updating-the-compat-data).
 - Search the informative text of the overview page for that interface, element, etc., for any references to the removed item. Add warning boxes in appropriate places with text along the lines of "\[item] has been removed from the specification and will be removed from browsers soon. See \[link to page] for a new way to do this."
 - Similarly, look for any discussion of the item in the guides and tutorials about the relevant API or technology. Add similar warnings.
 - Search MDN Web Docs for references to the removed item, in case there are discussions elsewhere. Add similar warning boxes there as well.
@@ -90,14 +83,7 @@ If the item was implemented in any release version of any one or more browsers b
 
 If the item was implemented in one or more release builds of browsers without requiring a preference or a flag, mark the item as **deprecated**, as follows:
 
-- If the item has any documentation pages describing only that one item (such as {{domxref("RTCPeerConnection.close()")}}), add the [`deprecated_header`](https://github.com/mdn/yari/blob/main/kumascript/macros/Deprecated_Header.ejs) macro to the top of the page and add the following `status:` front-matter entry:
-
-  ```yaml
-  status:
-    - deprecated
-  ```
-
-- On the overview page for the element, interface, or API, find the list of items that includes the item that's been removed from the specification and add the [`deprecated_inline`](https://github.com/mdn/yari/blob/main/kumascript/macros/Deprecated_Inline.ejs) macro after the item's name in that list.
+- Update the item's status data in the browser-compat-data repository by [submitting a pull request](https://github.com/mdn/browser-compat-data/blob/main/docs/contributing.md#updating-the-compat-data).
 - Search the informative text of the overview page for that interface, element, etc., for any references to the removed item. Add warning boxes in appropriate places with text along the lines of "\[item] has been removed from the specification and is deprecated. It may be removed from browsers in the future, so you should not use it. See \[link to page] for a new way to do this."
 - Similarly, look for any discussion of the item in the guides and tutorials about the relevant API or technology. Add similar warnings.
 - Search MDN Web Docs for references to the removed item, in case there are discussions elsewhere. Add similar warning boxes there as well.
@@ -117,3 +103,7 @@ For example, as of Jan 2019, the [`inputmode`](/en-US/docs/Web/HTML/Global_attri
 > **Warning:** Specification conflict: The WHATWG specification lists [`inputmode`](https://html.spec.whatwg.org/multipage/interaction.html#attr-inputmode) and modern browsers are working towards supporting it.
 > The [W3C HTML 5.2 spec](https://html.spec.whatwg.org/multipage/index.html#contents), however, no longer lists it (i.e. marks it as obsolete).
 > You should consider the WHATWG definition as correct, until a consensus is reached.
+
+## See also
+
+- [Feature status macros](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status)

files/en-us/mdn/writing_guidelines/howto/write_an_api_reference/index.md

@@ -68,7 +68,7 @@ Before you start you should write down a list of all the pages you should create
 
 #### Overview pages
 
-A single API overview page is used to describe the role of the API, its top-level interfaces, related features contained in other interfaces, and other high level details.
+A single API overview page is used to describe the role of the API, its top-level interfaces, related features contained in other interfaces, and other high-level details.
 Its name and slug should be the name of the API plus "API" on the end. It is placed at the top level of the API reference, as a child of [https://developer.mozilla.org/en-US/docs/Web/API](/en-US/docs/Web/API).
 
 Example:
@@ -107,7 +107,7 @@ Examples:
 
 #### Constructor pages
 
-Each interface has 0 or 1 constructors, documented on a subpage of the interface's page. It describes the purpose of the constructor and shows what its syntax looks like, usage examples, browser compatibility information, etc. Its slug is the name of the constructor, which is exactly the same as the interface name, and the title is interface name, dot, constructor name, then parentheses on the end.
+Each interface has zero or one constructors, documented on a subpage of the interface's page. It describes the purpose of the constructor and shows what its syntax looks like, usage examples, browser compatibility information, etc. Its slug is the name of the constructor, which is exactly the same as the interface name, and the title is interface name, dot, constructor name, then parentheses on the end.
 
 Example:
 
@@ -145,7 +145,7 @@ Examples:
 
 #### Event pages
 
-Document events as sub pages of their target interfaces and use the slug _eventname_\_event with the title set to `Interface: eventName event`.
+Document events as subpages of their target interfaces and use the slug _eventname_\_event with the title set to `Interface: eventName event`.
 
 Don't create pages for `on` event handler properties. Mention both ways to access the event on the `eventName_event` page.
 
@@ -229,12 +229,7 @@ Now you should be ready to start writing your interface pages. Each interface re
 
 1. **\\{{APIRef}}**: Include the \\{{APIRef}} macro in the first line of each interface page, including the name of the API as an argument, so for example \\{{APIRef("Web Audio API")}}. This macro serves to construct a reference menu on the left-hand side of the interface page, including properties and methods, and other quick links as defined in the [GroupData](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json) macro (ask someone to add your API to an existing GroupData entry, or to create a new one, if it isn't already listed there). The menu will look something like the below screenshot.
    ![This screenshot shows a vertical navigation menu for the OscillatorNode interface, with multiple sublists for methods and properties, as generated by the APIRef macro ](apiref-links.png)
-2. **Standardization status**: The banner indicating the standardization status should be added next (these can be placed on the same line as the \\{{APIRef}} macro.):
-
-   - \\{{SeeCompatTable}} for an experimental feature (i.e. the spec is not at the CR level.)
-   - \\{{Deprecated_header}}
-   - \\{{Non-standard_header}}
-
+2. **Feature status**: A [banner indicating the feature status](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#feature_status_page_banners) (such as deprecated, non standard, or experimental) is added automatically, if needed. For that you need to [update the status in the browser-compat-data repository](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses).
 3. **Description**: the first paragraph of the interface page should provide a short concise description of the interface's overarching purpose. You may also want to include a couple more paragraphs if any additional description is required. If the interface is actually a dictionary, you should use that term instead of "interface".
 4. **Inheritance diagram:** Use the [`\{{InheritanceDiagram}}`](https://github.com/mdn/yari/blob/main/kumascript/macros/InheritanceDiagram.ejs) macro to embed an SVG inheritance diagram for the interface.
 5. **List of properties, List of methods**: These sections should be titled "Properties" and "Methods", and provide links (using the \\{{domxref}} macro) to a reference page for each property/method of that interface, along with a description of what each one does. These should be marked up using [description/definition lists](/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN#definition_lists). Each description should be short and concise — one sentence if possible. See the "Referencing other API features with the \\{{domxref}} macro" section for a quicker way to create links to other pages.
@@ -277,13 +272,9 @@ Property pages must have the following sections:
 1. **Title**: the title of the page must be **InterfaceName.propertyName**. The interface name must start with a capital letter. Although an interface is implemented in JavaScript on the prototype of objects, we don't include `.prototype.` in the title, like we do in the [JavaScript reference](/en-US/docs/Web/JavaScript/Reference).
 2. **\\{{APIRef}}**: Include the \\{{APIRef}} macro in the first line of each property page, including the name of the API as an argument, so for example \\{{APIRef("Web Audio API")}}. This macro serves to construct a reference menu on the left-hand side of the interface page, including properties and methods, and other quick links as defined in the [GroupData](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json) macro (ask someone to add your API to an existing GroupData entry, or to create a new one, if it isn't already listed there). The menu will look something like the below screenshot.
    ![This screenshot shows a vertical navigation menu for the OscillatorNode interface, with multiple sublists for methods and properties, as generated by the APIRef macro ](apiref-links.png)
-3. **Standardization status**: The banner indicating the standardization status should be added next to the interface name (these can be placed on the same line as the \\{{APIRef}} macro):
+3. **Feature status**: A [banner indicating the feature status](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#feature_status_page_banners) (such as deprecated, non standard, or experimental) is added automatically, if needed. For that you need to [update the status in the browser-compat-data repository](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses).
 
-   - \\{{SeeCompatTable}} for an experimental feature (i.e. the spec is not at the CR level.)
-   - \\{{Deprecated_header}}
-   - \\{{Non-standard_header}}
-
-4. **Description**: the first paragraph of the property page should provide a short, concise description of the property's overarching purpose. You may also want to include a couple more paragraphs if any additional description is required. Obvious extra information to include is its default/initial value, and whether it's read only or not. The structure of the first sentence must be:
+4. **Description**: the first paragraph of the property page should provide a short, concise description of the property's overarching purpose. You may also want to include a couple more paragraphs if any additional description is required. Obvious extra information to include is its default/initial value, and whether it's read-only or not. The structure of the first sentence must be:
 
    - For read-only properties
      - : The **`InterfaceName.property`** read-only property returns a \\{{domxref("type")}} that…
@@ -315,11 +306,7 @@ Method pages need the following sections:
 1. **Title**: the title of the page must be **InterfaceName.method()** (with the two terminal parentheses), but the slug (the end of the page URL) must not include the parentheses. Also the interface name must start with a capital. Although an interface is implemented in JavaScript on the prototype of objects, we don't put `.prototype.` in the title, like we do in the [JavaScript reference](/en-US/docs/Web/JavaScript/Reference).
 2. **\\{{APIRef}}**: Include the \\{{APIRef}} macro in the first line of each method page, including the name of the API as an argument, so for example \\{{APIRef("Web Audio API")}}. This macro serves to construct a reference menu on the left-hand side of the interface page, including properties and methods, and other quick links as defined in the [GroupData](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json) macro (ask someone to add your API to an existing GroupData entry, or to create a new one, if it isn't already listed there). The menu will look something like the below screenshot.
    ![This screenshot shows a vertical navigation menu for the OscillatorNode interface, with multiple sublists for methods and properties, as generated by the APIRef macro ](apiref-links.png)
-3. **Standardization status**: Next, the banner indicating the standardization status should be added (these can be placed on the same line as the \\{{APIRef}} macro):
-
-   - \\{{SeeCompatTable}} for an experimental feature (i.e. the spec is not at the CR level.)
-   - \\{{Deprecated_header}}
-   - \\{{Non-standard_header}}
+3. **Feature status**: A [banner indicating the feature status](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#feature_status_page_banners) (such as deprecated, non standard, or experimental) is added automatically, if needed. For that you need to [update the status in the browser-compat-data repository](/en-US/docs/MDN/Writing_guidelines/Page_structures/Feature_status#how_to_add_or_update_feature_statuses).
 
 4. **Description**: The first paragraph of the method page should provide a short concise description of the method's overarching purpose. You may also want to include a couple more paragraphs if any additional description is required. Obvious extra information to include is its default parameter values, any theory that the method relies on, and what the parameter values do.