What we write
MDN Web Docs contains browser-neutral documentation that enables web developers to write browser-agnostic code. In this article, you'll find information about whether or not a given topic and/or type of content should be included on MDN Web Docs.
This section describes the policies set by the Mozilla MDN staff to govern the content on MDN Web Docs. All contributors to MDN Web Docs are expected to abide by these policies.
All content on MDN Web Docs must be relevant to the technology section in which it appears. Spam (commercial advertisement) and other irrelevant content will never be accepted onto the site. Contributors who keep trying to submit spam may be banned from MDN at the discretion of Mozilla MDN staff.
Outbound links to commercial sites that are relevant to the topic from which they are linked will be judged on a case-by-case basis. Their value in aiding web developers must outweigh the commercial benefit to the linked site.
Articles on MDN Web Docs must maintain a neutral point-of-view, reporting on browser variations without editorial bias. Derogatory comments about any browser or user agent is not acceptable.
Web technologies to be documented on MDN Web Docs should be on a standards track and must be implemented by at least one rendering engine. Variations in browser support are documented in the browser compatibility section of an article.
If you'd like to suggest content for MDN Web Docs, please make sure you read this page before submitting to ensure what you are suggesting is appropriate.
For new reference pages or guides, please open a discussion on our community repository outlining what content you are suggesting and why (please be as explicit as possible).
For suggesting larger projects that involve new sections of content, please refer to the Criteria for inclusion page, which also outlines the application process.
In general, if it's an open web technology, we document it on MDN Web Docs. This includes any feature that can be used by web developers to create websites and applications, now and in the near future.
If a feature is implemented by multiple browsers and either accepted as standard or is progressing towards standardization, then yes, we definitely document it here. If a feature is still very experimental and not implemented in multiple browsers and/or liable to change, then it is still suitable for inclusion, but may not be seen as a priority for the writing team to work on.
In other words, web technologies to be documented on MDN Web Docs should fulfil the following criteria:
- Be on a standards track.
- Be specified in a specification published by a reliable standards body.
- Be implemented by at least one rendering engine.
- Be released in a stable browser version.
Our primary focus is to write about the following front-end web technologies:
Note: Backend technologies usually have their own documentation elsewhere that MDN Web Docs does not attempt to supersede, although we do have some exceptions.
All content on MDN Web Docs must be relevant to the technology section in which it appears. Contributors are expected to follow these MDN writing guidelines for writing style, code samples, and other topics.
For more details about the criteria for whether or not a technology can be documented on MDN Web Docs, see the Criteria for inclusion page.
On MDN Web Docs, we are constantly looking to document new web standards technologies as appropriate. We try to strike a balance between publishing the documentation early enough so that developers can learn about new features as soon as they need to and publishing it late enough so that the technology is mature and stable so that the documentation won't need constant updates or rapid removal.
In general, our definition of the earliest we'll consider documenting a new technology is:
"When the feature is on a standards track and is implemented somewhere."
We consider documenting a new technology if it is:
- Specified in a specification document published under a reliable standards organization (such as W3C, WHATWG, Khronos, IETF, etc.) and has reached a reasonable level of stability (e.g., a W3C working draft or candidate recommendation or when the specification is looking fairly stable judging by the flow of issues filed against it).
- Implemented consistently in at least one browser, with other browser developers showing signs of interest (such as an active ticket or an "intent to implement" process is in effect).
We do not document a new technology if:
- It doesn't have a specification or the specification is a rough note that looks liable to change.
- One or zero browsers have currently implemented it and non-supporting browsers are not showing signs of interest in implementing it. You can gauge this by asking engineers who work on those browsers and by looking at browser bug trackers and mailing lists, etc.
- Isn't a web-exposed technology and/or is completely proprietary.
- It's already showing signs of being deprecated or superseded by a similar feature.
In general, anything that isn't an open web standard does not belong on MDN Web Docs. Spam (commercial advertisement) and other irrelevant content will never be accepted into the site. Contributors who keep trying to submit spam may be banned from MDN at the discretion of Mozilla MDN staff.
Examples of inappropriate topics for MDN Web Docs include:
- Technology that is not exposed to the web and is specific to a browser.
- Technology that is not related to the web.
- Documentation for end-users. For Mozilla products, for example, such documentation belongs on the Mozilla support site.
- Self-linking or self-promoting external links. Check out these guidelines in our writing style guide before adding an external link.
Pages are deleted from MDN Web Docs if they don't contain information that is useful in any way anymore, are out-of-date enough, and/or might be incorrect to the point where keeping them around might be misleading.
The following examples describe situations when pages/content might be deleted:
- Articles contain information about features that weren't implemented across all browsers and were later withdrawn (usually experimental features such as prefixed functionality).
- Reference pages describe features that were removed from the specification before they were implemented in any browser.
- Articles cover techniques that were later shown to be bad practices and superseded by better techniques.
- Articles contain information that were later replaced by other, better quality articles.
- Articles contain content that is inappropriate for MDN Web Docs.
- Sections of MDN Web Docs are not focused on open web technologies and are a maintenance burden.
For more information on how to delete documents, please see the Creating, moving and deleting pages guide.
Generally, our documentation falls into the following categories:
In general, MDN Web Docs is for product documentation, not for project or process documentation. So, if the document is about "how to use a thing" or "how a thing works" (where, the "thing" is in one of the topic categories mentioned above), then it can go on MDN Web Docs.
If a document is about "who's working on developing a thing" or "plans for developing a thing", then it shouldn't go on MDN Web Docs.
Here are some examples of types of documents that should not be placed on MDN Web Docs:
- Planning documents
- Design documents
- Project proposals
- Specifications or standards
- Promotional material, advertising, or personal information