Best practices

This article describes recommended ways of working with content on MDN. These guidelines describe preferred ways of doing things that lead to better results, or offer advice on deciding among multiple ways of doing similar things.

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.

• 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 Obsolete 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 Deprecated 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

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