Update contribtion docs for new mixin guideline

files/en-us/mdn/contribute/changelog/index.html

@@ -10,6 +10,21 @@
 
 <p>This document provides a record of MDN content processes, constructs, and best practices that have changed, and when they changed. It is useful to allow regular contributors to check in and see what has changed about the process of creating content for MDN.</p>
 
+<h2 id="february_2021">February 2021</h2>
+
+<h3 id="documenting_mixins">Documenting mixins</h3>
+
+<p><a href="https://heycam.github.io/webidl/#idl-interface-mixins">Interface mixins</a> in Web IDL are used in specifications to define Web APIs.
+For web developers, they aren't observable directly; they act as helpers to avoid repeating API definitions.</p>
+
+<p>Previously we commonly defined a landing page for a mixin class itself, and put the defined members on subpages underneath it,
+before linking to those from the landing pages of the interfaces that implement those mixins.
+This was confusing for readers because mixins are spec constructs — you never access the defined members using the mixin classes.
+To avoid this confusion we've instead put the pages for members defined on mixins directly under the implementing class pages.
+For more details, see the guide page on
+<a href="/en-US/docs/MDN/Contribute/Howto/Write_an_API_reference/Information_contained_in_a_WebIDL_file#mixins">how to write an API reference</a>
+and the discussion leading to this change at <a href="https://github.com/mdn/content/issues/1940">mdn/content#1940</a>.</p>
+
 <h2 id="january_2021">January 2021</h2>
 
 <h3 id="markup_for_note_and_warning_boxes">Markup for note and warning boxes</h3>

files/en-us/mdn/contribute/howto/write_an_api_reference/index.html

@@ -111,7 +111,7 @@ <h4 id="Interface_pages">Interface pages</h4>
 <ul>
  <li>We document methods defined on the <u>prototype</u> of an object implementing this interface (instance methods), and methods defined on the actual class itself (static methods). On the rare occasions that they both exist on the same interface, you should list them in separate sections on the page (Static methods/Instance methods). Usually only instance methods exist, in which case you can put these under the title "Methods".</li>
  <li>We do not document inherited properties and methods of the interface: they are listed on the respective parent interface. We do hint at their existence though.</li>
- <li>We do document properties and methods defined in mixins, though we use the mixin name as interface name. (This is not optimal as the mixin name will not appear in the console, but it prevents the duplication of documentation. We may revisit this in the future.)</li>
+ <li>We do document properties and methods defined in mixins. Please see the <a href="/en-US/docs/MDN/Contribute/Howto/Write_an_API_reference/Information_contained_in_a_WebIDL_file#mixins">contribution guide for mixins</a> for more details.</li>
  <li>Special methods like the stringifier (<code>toString()</code>) and the jsonizer (<code>toJSON()</code>) are also listed if they do exist.</li>
  <li>Named constructors (like <code>Image()</code>  for {{domxref("HTMLImageElement")}} ) are also listed, if relevant.</li>
 </ul>
@@ -275,7 +275,7 @@ <h3 id="Structure_of_an_interface_page">Structure of an interface page</h3>
    <li>\{{Non-standard_header}}</li>
   </ul>
  </li>
- <li><strong>Description</strong>: 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. Note that if the interface defines a mixin, you shouldn't use the term "Interface" to describe it, but mixin instead — it isn't really a standalone interface as such, but a mixin that adds functionality to multiple other interfaces. Similarly, if the interface is actually a dictionary, you should use that term instead of "interface".</li>
+ <li><strong>Description</strong>: 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".</li>
  <li><strong>Inheritance diagram:</strong> Use the {{TemplateLink("InheritanceDiagram")}} macro to embed an SVG inheritance diagram for the interface. For most interfaces, you won't need any parameters, but if the inheritance chain is long, you may need to use \{{InheritanceDiagram(600, 120)}} to make room vertically for two rows of boxes.</li>
  <li>
   <p><strong>List of properties, List of methods</strong>: 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, which can be created using the  "Definition List", "Definition  Term", and "Definition Description" buttons on the MDN editor toolbar. 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.<br>

files/en-us/mdn/contribute/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.html

@@ -91,18 +91,25 @@ <h3 id="Mixins">Mixins</h3>
 
 MyInterface includes MyMixin;</pre>
 
-<p>For documentation purposes, we create a mixin page, with the same structure as an interface page. As they are not true interfaces, the word <em>interface</em> is not used — <em>mixin</em> is used instead.</p>
+<p>For documentation purposes, MDN hides mixins. They are abstract and specification-only constructs.
+You can't see them in the browser console and it is more useful to know on which real interfaces methods and properties are implemented on.</p>
 
-<p>Mixin methods and properties are listed in the same way as regular methods and properties:</p>
+<p>If you encounter a mixin in IDL, like <a href="https://html.spec.whatwg.org/multipage/links.html#htmlhyperlinkelementutils">HTMLHyperlinkElementUtils</a>,
+search for the interfaces that implement the mixin, for example
+<a href="https://html.spec.whatwg.org/multipage/text-level-semantics.html#htmlanchorelement">HTMLAnchorElement</a>, and document the mixin members directly on those interfaces.
+</p>
 
+<p>In practice this means instead of documenting <code>HTMLHyperlinkElementUtils</code>,
+docs are added to the concrete interfaces, like <a href="/en-US/docs/Web/API/HTMLAnchorElement"><code>HTMLAnchorElement</code></a>
+and <a href="/en-US/docs/Web/API/HTMLAreaElement"><code>HTMLAreaElement</code></a>.</p>
+
+<p>See the following two pages that document <code>HTMLHyperlinkElementUtils.hash</code> accordingly:</p>
 <ul>
- <li>They have their own pages, prefixed with the mixin name. E.g {{domxref('Body.bodyUsed')}} or {{domxref('Body.blob()')}}.</li>
- <li>They are listed on the interface page when the interface <em>implements</em> the mixin. Unlike regular properties and methods, they are prefixed with the mixin name and not the interface name. You can see <code>Body</code> properties and methods listed on both {{domxref('Request')}} and {{domxref('Response')}} interfaces, as they both implement the <code>Body</code> mixin.</li>
+  <li><a href="/en-US/docs/Web/API/HTMLAnchorElement/hash"><code>HTMLAnchorElement.hash</code></a></li>
+  <li><a href="/en-US/docs/Web/API/HTMLAreaElement/hash"><code>HTMLAreaElement.hash</code></a></li>
 </ul>
 
-<div class="notecard note">
-<p><strong>Note:</strong> Mixin names do not appear in a Web developer console. We shouldn't show them, but we currently do this as it saves us from duplicating content, which would lead to a maintenance issue. We do this if the mixin is only used in one interface. (Such cases are bugs in the relevant specs. They shouldn't be defined as mixins, but as partial interfaces.)</p>
-</div>
+<p>For compat data, consult the <a href="https://github.com/mdn/browser-compat-data/blob/master/docs/data-guidelines.md#mixins">data guideline for mixins in BCD</a>.</p>
 
 <h3 id="Old_mixin_syntax">Old mixin syntax</h3>
 

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

@@ -61,13 +61,6 @@ <h2 id="Name_of_API_interfaces"><em>Name of API</em> interfaces</h2>
 	<dd>Include a brief description of the interface and what it does here. Include one term and definition for each interface or dictionary.</dd>
 </dl>
 
-<h3 id="Name_of_API_mixins"><em>Name of API</em> mixins</h3>
-
-<dl>
-	<dt>{{domxref("NameOfTheInterface")}}</dt>
-	<dd>Include a brief description of the mixin and what it does here. Include one term and definition for each mixin. If there are no mixins in this API, delete this section.</dd>
-</dl>
-
 <h3 id="Extensions_to_other_interfaces">Extensions to other interfaces</h3>
 
 <p>The <em>name of interface</em> extends the following APIs, adding the listed features.</p>