Writing guidelines

MDN Web Docs is an open-source project. The sections outlined below describe our guidelines for what we document and how we do it on MDN Web Docs. To learn about how to contribute, see our contribution guidelines.

What we write

This section covers what we include on MDN Web Docs and want we don't, as well as a number of other policies, such as when we write about new technologies, the content suggestion process, and whether we accept external links. This is a good place to start if you're considering writing or updating content for us. This section also includes:

Inclusion criteria

Provides an in-depth criteria for content to be included on MDN Web Docs, the application process for getting new documentation added on MDN Web Docs, and the expectations and guidelines for a party applying.

Our writing style guide

The writing style guide covers the language and style we use to write on MDN Web Docs. It also covers how to format code examples.

How to write for MDN Web Docs

This section covers all the information for creating and editing pages, including certain processes and techniques we adhere to. This section provides information about getting started, a general overview into how pages are structured, and where to find how-tos on specific tasks. This section includes topics such as:

How to research a technology

This section provides some handy tips for researching a technology you are documenting.

How to create, move, and delete pages

This section explains how we create, move, or delete a page on MDN Web Docs. It also explains how we redirect a page when moving or deleting the page.

How to use markdown

The markdown format we use derives from GitHub flavored markdown (GFM). This section is a guide to the markdown we use on MDN Web Docs, including formats for specific in-page components, such as notes and definition lists.

Adding images and media

This section describes the requirements for including media in pages, such as images.

How to document a CSS property

This article explains how to write a CSS property page, including layout and content.

How to document an API reference

This section explains how to approach documenting a Web API.

How to document an HTTP header

This article explains how to create a new reference page for an HTTP header.

How to add an entry to the glossary

This article explains how to add and link to entries in the MDN Web Docs glossary. It also provides guidelines about glossary entry layout and content.

Page types on MDN Web Docs

Each page on MDN Web Docs has a specific page type, whether that's a CSS reference page or a JavaScript guide page. This section lists the different page types and provides templates for each type. It's a good idea to browse these to understand which page type you are writing.

Page structures on MDN Web Docs

This section covers the various page structures that we use to provide consistent presentation of information on MDN Web Docs. This includes:

Syntax sections

The syntax section of a reference page on MDN Web Docs contains a syntax box defining the exact syntax of a feature. This article explains how to write syntax boxes for reference articles.

Code examples

There are a lot of different ways to include code examples on pages. This section outlines them and provides syntax guidelines for the different languages.

Banners and notices

Sometimes, an article needs a special notice added to it. This might happen if the page covers deprecated technology or other material that shouldn't be used in production code. This article covers the most common cases and how to do handle them.

Specification tables

Every reference page on MDN Web Docs 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 add them.

Compatibility tables

MDN Web Docs has a standard format for compatibility tables for our open web documentation. This article explains how to add to and maintain the database that is used to generate the compatibility tables as well as how to integrate the tables into articles.

Macros

Macros are shortcuts that are used in pages to generate content, such as sidebars. This section lists the macros we use and what they do.

How to label a technology

This section covers our definitions for the terms obsolete, deprecated, and experimental and provides guidelines on when we remove content from MDN Web Docs.

This section describes what copyright license content is and how to attribute correctly.