API references - The MDN project 编辑

Client-side JavaScript APIs form a large part of the technology available on the web, and MDN includes extensive reference material to explain what functionality is available in these APIs, and how to use it. In this set of guides we explain how to create API reference material on MDN.

Prerequisite resources

Before starting to document an API, you should have available:

1. 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.
2. The latest modern web browsers: These should be experimental/alpha builds such as Firefox Nightly/Chrome Canary that are more likely to support the features you are documenting. This is especially pertinent if you are documenting a nascent/experimental API.
3. Demos/blog posts/other info: Find as much info as you can. 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.
4. 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:
   • Your internal company address book, if you work for a relevant company.
   • A public mailing list that is involved in the discussion of that API,  such as Mozilla's dev-platform or dev-webapi lists, or a W3C list like public-webapps.
   • The spec itself. For example, the Web Audio API spec lists the authors and their contact details at the top.

High level structure

What does an API reference need?

This article explains what pages are required for a complete API reference.

Page types

There are a number of types of pages that are used repeatedly on MDN. This article describes these page types, their purpose, and gives examples of each and templates to use when creating a new page.

Individual page features

These articles explain how to create the individual page features required for API reference pages.

API reference sidebars

When including a sidebar on your MDN API reference articles, you are able to customize it so that it displays links to related Interfaces, tutorials, and other resources relevant just to that API. This article explains how.

Syntax sections

The syntax section of an MDN reference page contains a syntax box defining the exact syntax that a feature has (e.g. what parameters can it accept, which ones are optional?) This article explains how to write syntax boxes for reference articles.

Code examples

On MDN, you'll see numerous code examples inserted throughout the pages to demonstrate usage of web platform features. This article discusses the different mechanisms available for adding code examples to pages, along with which ones you should use and when.

Specification tables

Every reference page on MDN should provide information about the specification or specifications in which that API or technology was defined. This article demonstrates what these tables look like and explains how to construct them.

Compatibility tables

MDN has a standard format for compatibility tables for our open web documentation; that is, documentation of technologies such as the DOM, HTML, CSS, JavaScript, SVG, and so forth, that are shared across all browsers. This article covers how to use our features to add compatibility data to MDN pages.