Before starting to document an API, you should have available:
- 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.
- 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.
- 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.
- 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 refererence 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