initial commit

1 files changed, 446 insertions, 0 deletions

diff --git a/files/zh-cn/mdn/contribute/howto/write_an_api_reference/index.html b/files/zh-cn/mdn/contribute/howto/write_an_api_reference/index.html
new file mode 100644
index 0000000000..4ef7b2bcec
--- /dev/null
+++ b/files/zh-cn/mdn/contribute/howto/write_an_api_reference/index.html
@@ -0,0 +1,446 @@
+---
+title: How to write an API reference
+slug: MDN/Contribute/Howto/Write_an_API_reference
+tags:
+  - API
+  - Documentation
+  - Guide
+  - Howto
+  - MDN Meta
+  - NeedsTranslation
+  - TopicStub
+translation_of: MDN/Contribute/Howto/Write_an_API_reference
+---
+<div>{{MDNSidebar}}</div>
+
+<div class="summary">
+<p><span class="seoSummary">This guide takes you through all you need to know to write an API reference on MDN.</span></p>
+</div>
+
+<h2 id="Getting_prepared">Getting prepared</h2>
+
+<p>Before starting to document an API, there are some things you should prepare and plan in advance of starting to actually write.</p>
+
+<h3 id="Prerequisite_knowledge">Prerequisite knowledge</h3>
+
+<p>It is assumed that before reading this guide you have a reasonable knowledge of:</p>
+
+<ul>
+ <li>Web technologies like HTML, CSS and JavaScript. JavaScript is most important.</li>
+ <li>Reading Web technology specs. You'll be looking at these a lot as you document APIs.</li>
+</ul>
+
+<p>Everything else can be learned along the way.</p>
+
+<h3 id="Prerequisite_resources">Prerequisite resources</h3>
+
+<p>Before starting to document an API, you should have available:</p>
+
+<ol>
+ <li>The latest spec: Whether it is a W3C Recommendation or an early  editor's draft, you should refer to the latest available draft of the  spec that covers (or specs that cover) that API. To find it, you can usually do a Web search. The latest  version will often be linked to from all versions of the spec, listed under "latest draft" or similar.</li>
+ <li>The latest modern web browsers: These should be experimental/alpha builds such as <a href="https://nightly.mozilla.org/">Firefox Nightly</a>/<a href="https://www.google.com/intl/en/chrome/browser/canary.html">Chrome Canary</a> that are more likely to support the features you are documenting. This is especially pertinent if you are documenting a nascent/experimental API.</li>
+ <li>Demos/blog posts/other info: Find as much info as you can.</li>
+ <li>Useful engineering contacts: It is really useful to find yourself a friendly engineering contact to ask questions about the spec, someone who is involved in the standardization of the API, or its implementation in a browser. Good places to find them are:
+  <ul>
+   <li>Your internal company address book, if you work for a relevant company.</li>
+   <li>A public mailing list that is involved in the discussion of that API,  such as Mozilla's <a href="https://lists.mozilla.org/listinfo/dev-platform">dev-platform</a> or <a href="https://lists.mozilla.org/listinfo/dev-webapi">dev-webapi</a> lists, or a W3C list like <a href="https://lists.w3.org/Archives/Public/public-webapps/">public-webapps</a>.</li>
+   <li>The spec itself. For example, the <a href="https://webaudio.github.io/web-audio-api/">Web Audio API spec</a> lists the authors and their contact details at the top.</li>
+  </ul>
+ </li>
+</ol>
+
+<h3 id="Take_some_time_to_play_with_the_API">Take some time to play with the API</h3>
+
+<p>You will return to building demos many times through the course of documenting an API, but it is useful to start by spending time familiarizing yourself with how the API works — learn what the main interfaces/properties/methods are, what the primary use cases are, and how to write simple functionality with it.</p>
+
+<p>When an API has changed, you need to be careful that existing demos you refer to or learn from are not out of date. Check the main constructs that are used in the demo to see if they match up to the latest spec. They may also not work in up-to-date browsers, but this is not a very reliable test, as often the old features continue to be supported for backwards compatibility.</p>
+
+<div class="note">
+<p><strong>Note</strong>: If the spec has been recently updated so that, say, a method is now defined differently, but the old method still works in browsers, you will often have to document both in the same place, so that the old and new methods are covered. If you need help, refer to demos you have found, or ask an engineering contact.</p>
+</div>
+
+<h3 id="Create_the_list_of_documents_you_need_to_write_or_update">Create the list of documents you need to write or update</h3>
+
+<p>Reference documents for an API are quite numerous. There is an overview page for the API, a page for each interface, one for each method (including constructors) and property (including event handlers properties). There is also one page per event.</p>
+
+<h4 id="Overview_page">Overview page</h4>
+
+<p>The API overview page described the role of the API and the top-level interfaces. Its name is NAME OF API and its slug (that is the end part of the URL) must contains at least one space. It is placed at the top level of the API reference (<a href="/en-US/docs/Web/API">https://developer.mozilla.org/en-US/docs/Web/API</a>)</p>
+
+<ul>
+ <li>Title: <em>Web Audio API</em></li>
+ <li>Slug: <em>Web/API/Web_Audio_API</em></li>
+ <li>Tags: must include the 'Overview' and 'API' tags</li>
+</ul>
+
+<p>Note that most API have a special sidebar with quicklinks. This sidebar lists all interfaces, and possibly tutorials and related API.</p>
+
+<h4 id="Interfaces">Interfaces</h4>
+
+<p>Each interface will have its own page too. It will describe the purpose of the interface and lists all constructors, methods, and properties. The title of the page will be the name of the interface (always starting with an uppercase letter), its slug, the interface name, will be at the top level of the API reference (<a href="/en-US/docs/Web/API">https://developer.mozilla.org/en-US/docs/Web/API</a>)</p>
+
+<ul>
+ <li>Title: <em>AudioContext</em></li>
+ <li>Slug: <em>Web/API/AudioContext</em></li>
+ <li>Tags: must include the API name as a tag (here <em>Web Audio API</em>), as well as <em>Interface.</em></li>
+</ul>
+
+<ul>
+ <li>Title: <em>AudioNode</em></li>
+ <li>Slug: <em>Web/API/AudioNode</em></li>
+ <li>Tags: must include the API name as a tag (here <em>Web Audio API</em>), as well as <em>Interface</em>.</li>
+</ul>
+
+<div class="note">
+<p><strong>Note:</strong> We document every property and interface appearing in the <u>prototype</u> of an object implementing this interface. This has the following consequences:</p>
+
+<ul>
+ <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 prevents the duplication of documentation. We may revisit this in the future.)</li>
+ <li>There is one subpage per method, or constructor: if there are several variants, with different parameters, we still create one subpage and use its Syntax section to list all variants.</li>
+ <li>Special methods like the stringfier (<code>toString()</code>) and the jsonizier (<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>
+</div>
+
+<h4 id="Properties">Properties</h4>
+
+<p>The set of properties of a given interface can be found on its <a href="/en-US/docs/MDN/Contribute/Howto/Write_an_API_reference/Information_contained_in_a_WebIDL_file#Properties">WebIDL</a>. We document each one in a single page. It will describe the purpose of the property, its syntax, and provide examples of use, in isolation. Its slug is the property name, as a subpage of the interface:</p>
+
+<ul>
+ <li>Title: <em>AudioContext.currentTime</em></li>
+ <li>Slug: <em>Web/API/AudioContext/currentTime</em></li>
+ <li>Tags: must contain the API name as a tag (here <em>Web Audio API</em>), the interface name (here <em>AudioContext</em>) as well as <em>Property</em>. If the property is read-only, like this example, <em>Read-only</em> must be added too.<br>
+   </li>
+ <li>Title: <em>AudioNode.numberOfInputs</em></li>
+ <li>Slug: <em>Web/API/AudioNode/numberOfInputs</em></li>
+ <li>Tags: must include the API name as a tag (here <em>Web Audio API</em>), as well as <em>Interface</em>.</li>
+</ul>
+
+<div class="note">
+<p><strong>Note:</strong> Event handlers properties (<code>onXYZ</code> properties) are also listed: they'll have their individual subpage, like any other property.</p>
+</div>
+
+<h4 id="Methods">Methods</h4>
+
+<p>Like for properties, methods are listed on the interface's <a href="/en-US/docs/MDN/Contribute/Howto/Write_an_API_reference/Information_contained_in_a_WebIDL_file#Methods">WebIDL</a> and we document each method in a single page. It will describe the purpose of the method, its syntax, and provide examples of use, in isolation. Its slug, without the parenthesis, is the method name, as a subpage of the interface:</p>
+
+<ul>
+ <li>Title: <em>AudioContext.createBuffer()</em> Note the parentheses, making it clear that it is a method.</li>
+ <li>Slug: <em>Web/API/AudioContext/createBuffer </em>No parenthesis here.</li>
+ <li>Tags: must include the API name as a tag (here <em>Web Audio API</em>), the interface name (here <em>AudioContext</em>) as well as <em>Method</em>.</li>
+</ul>
+
+<h4 id="Constructors">Constructors</h4>
+
+<p>Similar in structure to methods, they also have their own pages. Note that only one unnamed constructor may exist per interface. The title convention is slightly different than the one of methods: it isn't prefixed.</p>
+
+<ul>
+ <li>Title: <em>Worker() </em>Note the parenthesis and the absence of prefix</li>
+ <li>Slug: <em>Web/API/Worker/Worker</em> No parenthesis here. Constructors are also subpages of the interface page.</li>
+ <li>Tags: must include the API name as a tag (here <em>Web Workers</em>), the interface name (here Worker) as well as<em> Constructor</em>.</li>
+</ul>
+
+<h4 id="Events">Events</h4>
+
+<p>Events are the last type of objects needing documentation. Unless the previous documents, event subpages lies under the Web/Events hierarchy. Each event has its own subpage:</p>
+
+<ul>
+ <li>Title: <em>start</em></li>
+ <li>Slug: <em>Web/Events/start</em></li>
+</ul>
+
+<h4 id="Listing_them_all">Listing them all</h4>
+
+<p>Creating a list of all these subpages is a good way to track them. For example:</p>
+
+<ul>
+ <li>Web_Audio_API</li>
+ <li>AudioContext
+  <ul>
+   <li>AudioContext.currentTime</li>
+   <li>AudioContext.destination</li>
+   <li>AudioContext.listener</li>
+   <li>  ...</li>
+   <li>AudioContext.createBuffer()</li>
+   <li>AudioContext.createBufferSource()</li>
+   <li>  ...</li>
+  </ul>
+ </li>
+ <li>AudioNode
+  <ul>
+   <li>AudioNode.context</li>
+   <li>AudioNode.numberOfInputs</li>
+   <li>AudioNode.numberOfOutputs</li>
+   <li>  ...</li>
+   <li>AudioNode.connect(Param)</li>
+   <li>  ...</li>
+  </ul>
+ </li>
+ <li>AudioParam</li>
+ <li>Events (update list)
+  <ul>
+   <li>start</li>
+   <li>end</li>
+   <li>…</li>
+  </ul>
+ </li>
+</ul>
+
+<p>Each interface in the list has a separate page created for it as a subpage of https://developer.mozilla.org/en-US/docs/Web/API; for example, the document for {{domxref("AudioContext")}} would be located at https://developer.mozilla.org/en-US/docs/Web/API/AudioContext. Each {{anch("Interface pages", "interface page")}} explains what that interface does and provides a list of the methods and properties that comprise the interface. Then each method and property is documented on its own page, which is created as a subpage of the interface it's a member of. For instance, {{domxref("AudioContext.currentTime")}} is documented at https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/currentTime.</p>
+
+<p>For example, given the list above, the {{domxref("AudioContext")}} interface is documented at https://developer.mozilla.org/en-US/docs/Web/API/AudioContext</p>
+
+<h3 id="Create_the_overview_page">Create the overview page</h3>
+
+<p>Now create the overview (API landing) page:</p>
+
+<ol>
+ <li>Go to <a href="/en-US/docs/Web/API">https://developer.mozilla.org/en-US/docs/Web/API</a> and, making sure you are logged in, select the <em>Cog icon &gt; New sub-page</em>. You should now be in an editor for a new page.</li>
+ <li>Enter the title as the API name as defined by the spec, plus "API". So for example "Web Audio API", "IndexedDB API", or "MediaRecorder API".</li>
+ <li>The Slug should be auto-filled, with underscores in the place of spaces. If it isn't, correct it.</li>
+ <li>Enter some dummy content into the large content area, such as "TBD" or "Content", then click <em>Save Changes</em>. Or just soar right on into the section {{anch("Overview page")}} and start filling out the real content right away.</li>
+</ol>
+
+<p>Your landing page now exists! Now all you have to do is fill it in, which is discussed in the next section.</p>
+
+<h2 id="Structure_of_an_overview_page">Structure of an overview page</h2>
+
+<div class="warning">
+<p><strong>Important</strong>: This section is still a proposal, without consensus yet reached. Don't use it yet.</p>
+</div>
+
+<p>API landing pages will differ greatly in length, depending on how big the API is, but they will all have basically the same features. See <a href="/en-US/docs/Web/API/Web_Audio_API">https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API</a> for an example of a big landing page.</p>
+
+<p>The features of a landing page are outlined below:</p>
+
+<ol>
+ <li><strong>Description</strong>: the first paragraph of the landing page should provide a short, concise description of the API's overarching purpose.</li>
+ <li><strong>Concepts and usage section</strong>: The next section should be titled "[name  of  API] concepts and usage", and provide an overview of all the main functionality that the API provides, what problems it solves, and how it  works — all at a high level. This section should be fairly short,  and not go into code or specific implementation details.</li>
+ <li><strong>List of interfaces</strong>: This section should be titled "[name of API]  interfaces", and provide links to the reference page for each interface that makes up the API, along with a short description of what each one does. See the "Referencing other API features with the \{{domxref}} macro" section for a quicker way to create new pages. Only current interfaces should be in this list; obsolete ones should be placed in (or moved into, if obsoleted after initially being documented) the following section.</li>
+ <li><strong>Obsolete interfaces:</strong> This section lists obsolete interfaces. <em>Ed. note: should this be a subsection of the main "Interfaces" section above?</em></li>
+ <li><strong>List of mixins</strong>: If any mixins are defined on the API spec, list them under a separate section, as they aren't interfaces as such.</li>
+ <li><strong>Example</strong>: This section should show a simple use case for the API.</li>
+ <li><strong>Specifications table</strong>: At this point you need to include a  specifications table — see the "Creating a spec reference table"  section for more details.</li>
+ <li><strong>Browser compatibility</strong>: Now you need to include a browser compatibility table. See <a href="/en-US/docs/MDN/Contribute/Structures/Compatibility_tables">Compatibility tables</a> for details.</li>
+ <li><strong>See also</strong>: The "See also" section is a good place to include further links that may be useful when learning about this technology, including MDN (and external) tutorials, examples, libraries, etc.</li>
+ <li><strong>Tags</strong>: There is a set of standard tags you should include for each reference page — see the "Tags" section for more.</li>
+</ol>
+
+<h2 id="Structure_of_an_interface_page">Structure of an interface page</h2>
+
+<p>Now you should be ready to start writing your interface pages. Each interface reference page should observe the following structure:</p>
+
+<ol>
+ <li><strong>\{{APIRef}}</strong>: 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 quicklinks as defined in the <a href="https://github.com/mdn/kumascript/blob/master/macros/GroupData.json">GroupData</a> 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.<br>
+  <img alt="This screenshot shows a vertical navigation menu for the OscillatorNode interface, with multiple sublists for methods and properties, as generated by the APIRef macro " src="https://mdn.mozillademos.org/files/8783/apiref-links.png" style="border-style: solid; border-width: 1px; display: block; height: 384px; margin: 0px auto; width: 302px;"></li>
+ <li><strong>Standardization status</strong>: The banner indicating the standardization status should be added next (these can be placed on the same line as the \{{APIRef}} macro.):
+  <ul>
+   <li>\{{SeeCompatTable}} for an experimental feature (i.e. the spec is not at the CR level.)</li>
+   <li>\{{Deprecated_header}}</li>
+   <li>\{{Obsolete_header}}</li>
+   <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>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>
+   <br>
+   At the beginning of both sections, before the beginning of the list of properties/methods, indicate inheritance using the appropriate sentence, in italics:<br>
+   <em>This interface doesn't implement any specific properties, but inherits properties from \{{domxref("XYZ")}}, and \{{domxref("XYZ2")}}.</em><br>
+   <em>This interface also inherits properties from </em><em>\{{domxref("XYZ")}}, and \{{domxref("XYZ2")}}.<br>
+   This interface doesn't implement any specific methods, <em>but inherits methods from \{{domxref("XYZ")}}, and \{{domxref("XYZ2")}}.</em><br>
+   <em>This interface also inherits methods from </em><em>\{{domxref("XYZ")}}, and \{{domxref("XYZ2")}}.</em></em></p>
+
+  <div class="note">
+  <p><strong>Note</strong>: If the interface features event handlers, put these inside the "Properties" section (they are a type of property) under a subheading of "Event handlers".</p>
+  </div>
+
+  <div class="note">
+  <p><strong>Note</strong>:  Properties that are read-only should have the \{{readonlyInline}} macro, which creates a nifty little "Read only" badge, included on the same line as their \{{domxref}} links (after the use of the \{{experimentalInline}}, \{{obsoleteInline}}, \{{non-standard_Inline}} and \{{deprecatedInline}} macros, if some of these are needed.</p>
+  </div>
+ </li>
+ <li><strong>Example</strong>: Include a code listing to show typical usage of a major feature of the API. Rather than listing ALL the code, you should list an interesting subset of it. For a complete code listing, you could reference a <a href="https://github.com/">Github</a> repo containing the full example, and you could  also link to a live example created using the <a href="https://help.github.com/articles/creating-project-pages-manually/">Github gh-pages </a>feature (so long as it uses only client-side code of course.) If the example is visual, you could also use the MDN <a href="/en-US/docs/MDN/Contribute/Editor/Live_samples">Live Sample</a> feature to make it live and playable in the page.
+  <div class="note">
+  <p><strong>Note</strong>: More details about writing code examples can be found in the "Examples" section.</p>
+  </div>
+ </li>
+ <li><strong>Specifications table</strong>: At this point you need to include a specifications table — see the "Creating a spec reference table" section  for more details.</li>
+ <li><strong>Browser compatibility</strong>: Now you need to include a browser compatibility table. See <a href="/en-US/docs/MDN/Contribute/Structures/Compatibility_tables">Compatibility tables</a> for details.</li>
+ <li><strong>Polyfill</strong>: If appropriate, include this section, providing code for a polyfill that enables the API to be used even on browsers that don't implement it. If no polyfill exists or is needed, leave this section out entirely.</li>
+ <li><strong>See also</strong>: The "See also" section is a good place to include further links that may be useful when learning about this technology, including MDN (and external) tutorials, examples, libraries, etc. We have a liberal policy for linking to external sources, but pay attention:
+  <ul>
+   <li>Do not include pages with the same information as another page in the MDN; link to that page instead.</li>
+   <li>Do not put author names — we are a writer-neutral documentation site. Link to the document; the author name will be displayed there.</li>
+   <li>Pay special attention to blog posts: they tend to become outdated (old syntax, wrong compat information). Link to them only if they have a clear added value that can't be found in a maintained document.</li>
+   <li>Do not use action verb like "See … for more information" or "Click to…", you don't know if your reader is able to see, or to click on the link (like on a paper version of the document).</li>
+  </ul>
+ </li>
+ <li><strong>Tags</strong>: There is a set of standard tags you should include for each reference page — see the "Tags" section for more.</li>
+</ol>
+
+<h3 id="Interface_page_examples">Interface page examples</h3>
+
+<p>The following are exemplary examples of Interface pages:</p>
+
+<ul>
+ <li>{{domxref("Request")}} from the <a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a>.</li>
+ <li>{{domxref("SpeechSynthesis")}} from the <a href="/en-US/docs/Web/API/Web_Speech_API">Web Speech API</a>.</li>
+</ul>
+
+<h2 id="Structure_of_a_property_page">Structure of a property page</h2>
+
+<p>You can now fill in your interface property pages. Since the structures of all of them are the same, it usually works best to open all the property  pages for each interface in separate tabs. From here you can fill one in fully, then copy its contents to all the other property pages and just update the bits that need changing,  rather than having to fill each one in from scratch.</p>
+
+<p>Edit the property page name to follow the <code>Interface.property_name</code> convention.</p>
+
+<p>Property pages must have the following sections:</p>
+
+<ol>
+ <li><strong>Title</strong>: the title of the page must be <strong>InterfaceName.propertyName</strong>. 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 <code>.prototype.</code> in the title, like we do in the <a href="/en-US/docs/Web/JavaScript/Reference">JavaScript reference</a>.</li>
+ <li><strong>\{{APIRef}}</strong>: 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 quicklinks as defined in the <a href="https://github.com/mdn/kumascript/blob/master/macros/GroupData.json">GroupData</a> 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.<br>
+  <img alt="This screenshot shows a vertical navigation menu for the OscillatorNode interface, with multiple sublists for methods and properties, as generated by the APIRef macro " src="https://mdn.mozillademos.org/files/8783/apiref-links.png" style="border-style: solid; border-width: 1px; display: block; height: 384px; margin: 0px auto; width: 302px;"></li>
+ <li><strong>Standardization status</strong>: 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):
+  <ul style="margin-left: 40px;">
+   <li>\{{SeeCompatTable}} for an experimental feature (i.e. the spec is not at the CR level.)</li>
+   <li>\{{Deprecated_header}}</li>
+   <li>\{{Obsolete_header}}</li>
+   <li>\{{Non-standard_header}}</li>
+  </ul>
+ </li>
+ <li><strong>Description</strong>: 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:
+  <dl>
+   <dt>For read-only properties</dt>
+   <dd>The <code><strong>InterfaceName.property</strong></code> read-only property returns a \{{domxref("type")}} that...</dd>
+   <dt>For other properties</dt>
+   <dd>The <strong><code>InterfaceName.property</code></strong> property is a \{{domxref("type")}} that…</dd>
+  </dl>
+
+  <div class="note"><strong>Note</strong>: <code>InterfaceName.property</code> should be in <code>&lt;code&gt;</code>, and should additionally be in bold (<code>&lt;strong&gt;</code>) the first time it's used.</div>
+ </li>
+ <li><strong>Syntax</strong>: The syntax section should show how to get the property, and how to set it, if it's not read only. Use the <code>syntaxbox</code> class for it and italics for part to be replaced by the actual variable name. For example:
+  <pre class="syntaxbox">var <em>myType</em> = <em>oscillator</em>.type;
+<em>oscillator</em>.type = <em>aType;</em>
+</pre>
+  The syntax section should also have a subsection — "Value", which will contain a description of the property's value. This should contain the data type of the property, and what it represents. For an example, see {{domxref("SpeechRecognition.grammars")}}</li>
+ <li>
+  <p><strong>Example</strong>: Include a code listing to show typical usage of the property in question. You should start with a simple example that shows how an object of the type is created and how to access the property. More complex examples can be added after such an example. In these additional examples, rather than listing ALL the code, you should list an interesting subset of it. For a complete code listing, you can reference a <a href="https://github.com/">Github</a> repo containing the full example, and you could also link to a live example created using the <a href="https://help.github.com/articles/creating-project-pages-manually/">github gh-pages feature</a> (so long as it uses only client-side code of course.) You can also make use of the <a href="/en-US/docs/MDN/Contribute/Tools/Sample_server">MDN Sample Server</a>, which is particularly helpful for more complex samples. If the example is visual, you could also use the MDN <a href="/en-US/docs/MDN/Contribute/Editor/Live_samples">Live Sample</a> feature to make it live and playable in the page.</p>
+
+  <div class="note"><strong>Note</strong>: If you make use of Github, the example must live under <a href="https://github.com/mdn/">github.com/mdn</a>. See the "Examples" section for more details.</div>
+ </li>
+ <li><strong>Specifications table</strong>: At this point you need to include a specifications table — see the "Creating a spec reference table"  section for more details.</li>
+ <li><strong>Browser compatibility</strong>: Now you need to include a browser compatibility table. See <a href="/en-US/docs/MDN/Contribute/Structures/Compatibility_tables">Compatibility tables</a> for details.</li>
+ <li><strong>See also</strong>: The "See also" section is a good place to include further links that may be useful when using this technology: like methods and properties affected by a change of this property or events thrown in relation to it. More links useful when learning about this technology, including MDN (and external) tutorials, examples, libraries,… can be added, though it may be useful to consider adding them on the interface reference page instead.</li>
+ <li><strong>Tags</strong>: There is a set of standard tags you should include for each property page — see the "Tags" section for more.</li>
+</ol>
+
+<h3 id="Property_page_examples">Property page examples</h3>
+
+<p>The following are exemplary examples of property pages:</p>
+
+<ul>
+ <li>{{domxref("Request.method")}} from the <a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a>.</li>
+ <li>{{domxref("SpeechSynthesis.speaking")}} from the <a href="/en-US/docs/Web/API/Web_Speech_API">Web Speech API</a>.</li>
+</ul>
+
+<h2 id="Structure_of_a_method_page">Structure of a method page</h2>
+
+<p>You can now fill in your interface method pages. Since the structure of  all of them are the same, one possible way of doing it is to open all the method pages for each interface in separate tabs. From here you can fill one in fully, then copy its contents to all the other method pages and just update the bits that need changing, rather than having to fill each one in from scratch.</p>
+
+<p>Method pages need the following sections:</p>
+
+<ol>
+ <li><strong>Title</strong>: the title of the page must be <strong>InterfaceName.method()</strong> (with the two terminal parentheses), but the slug (the end of the page URL) must not include the brackets. 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 <code>.prototype.</code> in the title, like we do in the <a href="/en-US/docs/Web/JavaScript/Reference">JavaScript reference</a>.</li>
+ <li><strong>\{{APIRef}}</strong>: 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 quicklinks as defined in the <a href="https://github.com/mdn/kumascript/blob/master/macros/GroupData.json">GroupData</a> 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.<br>
+  <img alt="This screenshot shows a vertical navigation menu for the OscillatorNode interface, with multiple sublists for methods and properties, as generated by the APIRef macro " src="https://mdn.mozillademos.org/files/8783/apiref-links.png" style="border-style: solid; border-width: 1px; display: block; height: 384px; margin: 0px auto; width: 302px;"></li>
+ <li><strong>Standardization status</strong>: Next, the banner indicating the standardization status should be added (these can be placed on the same line as the \{{APIRef}} macro):
+  <ul>
+   <li>\{{SeeCompatTable}} for an experimental feature (i.e. the spec is not at the CR level.)</li>
+   <li>\{{Deprecated_header}}</li>
+   <li>\{{Obsolete_header}}</li>
+   <li>\{{Non-standard_header}}</li>
+  </ul>
+ </li>
+ <li><strong>Description</strong>: 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.
+  <dl>
+   <dt>The beginning of the first sentence must follow the following structure:</dt>
+   <dd>The <strong>InterfaceName.method()</strong> method interface ...</dd>
+  </dl>
+
+  <div class="note"><strong>Note:</strong> <code>InterfaceName.method()</code> should be in <code>&lt;code&gt;</code>, and should also be in bold (<code>&lt;strong&gt;</code>) the first time it's used.</div>
+ </li>
+ <li><strong>Syntax</strong>: The syntax section should include a 2–3 line example — usually just construction of the  interface, then calling of the interface method.
+  <dl>
+   <dt>The syntax should be of the form:</dt>
+   <dd>var  &lt;em&gt;returnValue&lt;/em&gt; =  &lt;em&gt;ifName&lt;/em&gt;.method(&lt;em&gt;param1&lt;/em&gt;,  &lt;em&gt;param2&lt;/em&gt;, ...)</dd>
+   <dt>If the method has no return value (<code>void</code> as return value in the webidl), use:</dt>
+   <dd>&lt;em&gt;ifName&lt;/em&gt;.method(&lt;em&gt;param1&lt;/em&gt;,  &lt;em&gt;param2&lt;/em&gt;, ...)</dd>
+  </dl>
+  The syntax section should include three subsections (see {{domxref("SubtleCrypto.sign()")}} for an example):
+
+  <ul>
+   <li>"Parameters": This should contain a definition list (or unordered list) that names and describes the different parameters the method takes. You should include the {{optional_inline}} macro next to the parameter name, in the case of optional parameters. If there are no parameters, this section should be omitted.</li>
+   <li>"Return value": This should say what return value the method has, be it a simple value like a double or boolean, or a more complex value like another interface object, in which case you can use \{{domxref}} macro to link to the MDN API page covering that interface (if it exists.) A method might return nothing, in which case the return value should be written as "\{{jsxref('undefined')}}" (which will look like this in the rendered page: {{jsxref("undefined")}}).</li>
+   <li>"Exceptions": This should list the different exceptions that can be raised when invoking the method, and what circumstances cause them. If there are no exceptions, this section should be omitted.</li>
+  </ul>
+ </li>
+ <li><strong>Example</strong>: Include a code listing to show typical usage of the method in question. Rather than listing ALL the code, you should list an interesting subset of it. For a complete code listing, you should reference a <a href="https://github.com/">Github</a> repo containing the full example, and you could also link to a live example created using the <a href="https://help.github.com/articles/creating-project-pages-manually/">Github gh-pages feature</a> (so long as it uses only client-side code of course.) You can also make use of the <a href="/en-US/docs/MDN/Contribute/Tools/Sample_server">MDN Sample Server</a>, which is particularly helpful for more complex samples. See the "Examples" section for more details. If the example is visual, you could also use the MDN <a href="/en-US/docs/MDN/Contribute/Editor/Live_samples">Live Sample</a> feature to make it live and playable in the page.</li>
+ <li><strong>Specifications table</strong>: At this point you need to include a specifications table — see the "Creating a spec reference table" section for more details.</li>
+ <li><strong>Browser compatibility</strong>: Now you need to include a browser compatibility table. See <a href="/en-US/docs/MDN/Contribute/Structures/Compatibility_tables">Compatibility tables</a> for details.</li>
+ <li><strong>Polyfill</strong>: If appropriate (especially if common browsers are still shipping without support for the method), you can include a section which includes the code for a polyfill to allow the API to be used in browsers that don't implement it.</li>
+</ol>
+
+<h3 id="Method_page_examples">Method page examples</h3>
+
+<p>The following are exemplary examples of Interface pages:</p>
+
+<ul>
+ <li>{{domxref("Document.getAnimations()")}} from the <a href="/en-US/docs/Web/API/Web_Animations_API">Web Animations API</a>.</li>
+ <li>{{domxref("GlobalFetch.fetch()")}} from the <a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a>.</li>
+</ul>
+
+<h2 id="Tagging">Tagging</h2>
+
+<p>For API reference pages, there are standard tags that all pages should have:</p>
+
+<ul>
+ <li>"API"</li>
+ <li>"Reference"</li>
+ <li>Name of API (e.g. "Web Audio API")</li>
+ <li>Any pertinent related keywords (e.g. "audio") </li>
+</ul>
+
+<p>For Interface pages, also add:</p>
+
+<ul>
+ <li>"Interface"</li>
+ <li>The name of the interface, e.g. "AudioContext"</li>
+</ul>
+
+<p>For method pages, also add:</p>
+
+<ul>
+ <li>"Method"</li>
+ <li>The name of the interface the method relates to, e.g. "AudioContext"</li>
+ <li>The name of the method, e.g. "createBuffer"</li>
+</ul>
+
+<p>For property pages, also add:</p>
+
+<ul>
+ <li>"Property"</li>
+ <li>The name of the interface the property relates to, e.g. "AudioContext"</li>
+ <li>The name of the property, e.g. "currentTime" </li>
+</ul>
+
+<p>In all cases, also add a keyword indicating the standardization status:</p>
+
+<ul>
+ <li>Experimental (if the spec is not a CR)</li>
+ <li>Deprecated</li>
+ <li>Obsolete</li>
+ <li>Non-standard</li>
+</ul>
+
+<p>These tags will be used to generate correct quicklinks, with nice icons. See <a href="/en-US/docs/MDN/Contribute/Howto/Tag">How to properly tag pages</a> for additional information on tagging, as well as about other tags you may find useful.</p>