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 what 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.

• Learn web development writing guidelines

  • : The Learn web development section of MDN is aimed specifically at folks learning the basic fundamentals of web development, and as such, requires a different approach to the rest of MDN’s content. This articles provides guidelines for writing learning content.

• 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 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.

• Attributions and copyright licensing information

  • : Describes our policy on using MDN Web Docs content elsewhere on the web, how to get permission to republish content on MDN, and hints for linking to MDN content.

• How to label a technology

  • : This section covers our definitions for the terms obsolete, deprecated, and experimental and provides guidelines on how to label a technology with them, and when we remove content from MDN Web Docs.