MDN wants to learn about developers like you: https://qsurvey.mozilla.com/s3/d6d7ff2e2f9c

MDN conventions and definitions

This article defines some conventions and definitions that are commonly used on MDN, which might not be obvious to some people when they comes across them in the documentation.

Definitions

Deprecated and obsolete

Deprecated and obsolete are common terms associated with technologies and specifications, but what do they mean?

Deprecated
On MDN, the term deprecated used to mark an API or technology that is no longer recommended, but is still implemented and may still work. More recently, we've updated it to the definition used in our browser-compat-data project, which is that "the feature is no longer recommended. It might be removed in the future or might only be kept for compatibility purposes. Avoid using this functionality."
Obsolete
On MDN, the term obsolete used to mark an API or technology that is not only no longer recommended, but also no longer implemented in browsers. This was however confusing — it is similar to deprecated, and the distinction is not very helpful (you still shouldn't use it in a production site). We are therefore not using it anymore, and any instances you come across should be removed/replaced by deprecated.

Experimental

Experimental can mean different things depending on the context you hear or read it in. When a technology is described as experimental on MDN, it means that the technology is nascent and immature, and currently in the process of being added to the Web platform (or considered for addition).

One or both of these will be true:

  • It is implemented and enabled by default in less than two modern major browsers.
  • Its defining spec is not stable and likely to change significantly. Its syntax and behavior is therefore subject to change in future versions of browsers as the specification changes.

If one or both of these definitions is true, then you should think carefully before you start using that technology in any kind of production project (i.e. not just a demo or experiment). See also the definition of experimental in our browser-compat-data project.

Archived pages

Archived pages are pages that are stored in the MDN Archive of obsolete content. These pages contain information out-of-date enough that it is not directly useful to anyone anymore.

Most commonly, these concern Mozilla projects that have been discontinued and shouldn't be relied on anymore. But we don't simply delete them because they form a useful historical record, and some of the patterns or ideas contained within might be useful for future work. A good example is the B2G (Firefox OS) project.

When should a page be archived?

A page should be archived if it fits the above description. To archive a page, you should use the "Move page feature" (Advanced > Move this article) to move the page into the Archive page tree (/en-US/docs/Archive). You might not have the permissions to use this feature, and before you start archiving pages you should discuss it with the MDN community first — talk to us on our Discourse forum.

Deleted pages

Deleted pages are pages that have been explicitly deleted from MDN — see for example the SharedKeyframeList interface and SharedKeyframeList() constructor. These pages contain information that is not useful in any way anymore, and/or might be incorrect to the point where keeping it available might be confusing or bad for people to know.

These might be:

  • Reference pages for API features that were removed from the specification before they were implemented in any browsers.
  • Articles covering techniques that were later shown to be bad practice and superceded by better techniques.
  • Articles containing information that were later replaced by other, better quality articles.
  • Articles containing content that is inappropriate for MDN.
  • Translations that are old, out-of-date, and difficult to fix, meaning that the English version is preferrable and starting a new translation would be an easier option.

When should a page be deleted?

A page should be deleted if it fits the above description. To delete a page, you should use the "Delete this page feature" (Advanced > Delete this page) to delete the page. You will probably not have the permissions to use this feature, and when thinking about deleting pages you should discuss it with the MDN community first — talk to us on our Discourse forum.

Conventions

When something is removed from the specification

Sometimes during the development of a new specification, or over the course of the evolution of living standards such as HTML, new elements, methods, properties, and so forth are added to the specification, stay there for a while, then get removed again. Sometimes this happens very quickly, and sometimes these new items remain in the specification for months or even years before being removed. This can make it tricky to decide how to handle the removal of the item from the spec. Here are some guidelines to help you decide what to do.

For the purposes of this discussion, the word "item" is used to mean anything which can be part of a specification: an element or an attribute of an element, an interface or any individual method, property, or other member of an interface, and so forth.

  • If the item was never implemented in a release version of any browser—even behind a preference or flag—simply delete any references to the item from the documentation.
    • If the item has any documentation pages describing only that one item (such as RTCPeerConnection.close()), delete that page. If the removed item is an interface, this means removing any subpages describing the properties and methods on that interface as well.
    • Remove the item from any lists of properties, attributes, methods, and so forth. For methods of an interface, that means to remove it from the "Methods" section on the interface's overview page, for example.
    • Search the text of the overview page for that interface, element, etc. for any references to the removed item. Remove those references, being sure not to leave weird grammar issues or other problems with the text. This may mean not just deleting words but rewriting a sentence or paragraph to make more sense. It may also mean removing entire sections of content if the description of the item's use is lengthy.
    • Similarly, look for any discussion of the item in the guides and tutorials about the relevant API or technology. Remove those references, being sure not to leave weird grammar issues or other problems with the text. This may mean not just deleting words but rewriting a sentence or paragraph to make more sense. It may also mean removing entire sections of content if the description of the item's use is lengthy.
    • Search MDN for references to the removed item, in case there are discussions elsewhere. It's unlikely that there are, since if it was never implemented, it's unlikely to be widely discussed. Remove those mentions as well.
  • If the item was implemented in any release version of any one or more browsers—but only behind a preference or flag—do not delete the item from the documentation immediately. Instead, mark the item as obsolete as follows:
    • If the item has any documentation pages describing only that one item (such as RTCPeerConnection.close()), add the obsolete_header macro to the top of the page and add the tag to the page's list of tags.
    • On the overview page for the element, interface, or API, find the list of items which includes the item that's been removed from the specification and add the obsolete_inline macro after the item's name in that list.
    • Search the informative text of the overview page for that interface, element, etc. for any references to the removed item. Add warning boxes in appropriate places with text along the lines of "[whatever] has been removed from the specification and will be removed from browsers soon. See [link to page] for a new way to do this."
    • Similarly, look for any discussion of the item in the guides and tutorials about the relevant API or technology. Add similar warnings.
    • Search MDN for references to the removed item, in case there are discussions elsewhere. Add similar warning boxes there as well.
    • At some point in the future, a decision may be made to actually remove the item from the documentation; we don't normally do this but if the item was especially unutilized or uninteresting, we may decide to do so.
  • If the item was implemented in one or more release builds of browsers—without requiring a preference or flag to be changed—mark the item as deprecated, as follows:
    • If the item has any documentation pages describing only that one item (such as RTCPeerConnection.close()), add the deprecated_header macro to the top of the page and add the tag to the page's list of tags.
    • On the overview page for the element, interface, or API, find the list of items which includes the item that's been removed from the specification and add the deprecated_inline macro after the item's name in that list.
    • Search the informative text of the overview page for that interface, element, etc. for any references to the removed item. Add warning boxes in appropriate places with text along the lines of "[whatever] has been removed from the specification and is deprecated. It may be removed from browsers in the future, so you should not use it. See [link to page] for a new way to do this."
    • Similarly, look for any discussion of the item in the guides and tutorials about the relevant API or technology. Add similar warnings.
    • Search MDN for references to the removed item, in case there are discussions elsewhere. Add similar warning boxes there as well.
    • It's unlikely that these items will be removed from the documentation anytime soon, if ever. It's possible, however, that some or all of the material may be moved to the Archive section of the site.

Please use common sense with wording of warning messages and other changes to text suggested by the guidelines above. Different items will require different wording and handling of the situation. When in doubt, feel free to ask for advice on the #mdn channel on IRC, or on the dev-mdc mailing list.

Copying content within MDN

Sometimes, you need to reuse the same text on multiple pages (or you want to use one page's content as a template for another page). You have three options:

  • If you want to copy an entire page:
    1. While viewing the page you want to copy, on the Advanced (gear) menu, choose  Clone this page. This opens the editor UI for a new page, with the contents of the cloned page already populated.
    2. Enter a new Title and Slug for the cloned page.
    3. Edit the contents of the page as needed, and save as usual.
  • If you want to copy just part of a page, don't just visit the page and copy from it. This introduce unwanted additional bits of HTML into the destination page, and somebody will have to clean that up, you or another editor. Nobody wants that. To copy part of an MDN page to another page:
    1. On the source page, click the Edit button on the source page.
    2. Copy the content you want to reuse from within the editor UI.
    3. Click Discard to exit the editor UI for that page.
    4. Open the editor UI for page where you want to paste.
    5. Paste the content from the clipboard.
  • Sometimes you literally want to use the same content on many pages. In this case, you might be best off placing the content in one page, then using the Page macro to transclude the material from one page into another. This way, whenever the text on the source page is updated, the destination page will update as well (that is, this will happen on a forced-refresh or when the target page goes through a scheduled rebuild).

Copying content from elsewhere

Often, there is useful content about a topic somewhere on the web besides on MDN. However, copying such content can be fraught with difficulties, both legal and technical.

On the technical level, search engines typically penalize a site in their rankings for reproducing content available elsewhere. Therefore, it is preferable to have original content on MDN, to enhance the search engine ranking of MDN's content. You can link to the existing content from MDN.

On the legal level, you must be authorized to contribute the content, and it must be licensed and attributed in a way that is compatible with MDN's license.

  • If you created the existing content (for your own purposes and not as work-for-hire), and you are willing to contribute it to MDN under MDN's license, this is the easiest case, and you are free to contribute the content.
  • If the copyright for the content belongs to someone else, it must be licensed and attributed compatibly with MDN's license. It is often not easy for someone who is not a lawyer to determine what licenses are compatible. To be on the safe side, contact a member of the MDN staff team, who may consult Mozilla's Legal team for guidance if necessary.

 

Document Tags and Contributors

 Contributors to this page: chrisdavidmills, wbamberg, jswisher, Sheppy
 Last updated by: chrisdavidmills,