--- title: MDN - Convenções e Definições slug: MDN/Guidelines/Convencoes_definicoes tags: - Documentação - Guía - Linhas Diretrizes - MDN - Metadados MDN translation_of: MDN/Guidelines/Conventions_definitions ---

Este artigo define algumas convenções e definições que são normalmente utilizadas na MDN, que talvez não sejam óbvias para algumas pessoas quando elas as encontrarem na documentação.

Definições

Desaprovada e obsoleta

Desaprovada e obsoleta são termos comuns associados com as tecnologias e especificações, mas o que eles significam?

Desaprovada: Na MDN, o termo 'desaprovada' utilizado para marcar uma API ou tecnologia que já não é recomendada, mas que ainda está implementada e poderá funcionar. Mais recentemente, nós atualizamos-la para a definição utilizada no projeto de dados compatíveis do navegador, que é que "a funcionalidade já não é mais recomendada. Esta poderá ser removida no futuro ou pode ser mantida apenas para fins de compatibilidade. Evite utilizar esta funcionalidade".
Obsoleta: No MDN, o termo 'obsoleta'utilizado para marcar uma API ou tecnologia que já não é mais recomendada, mas também não é mais implementada nos navegadores. Isto foi no entanto confuso - é semelhante a obsoleta, e a distinção não é muito útil (ainda não o deveria utilizar num site de produção). Portanto, nós não estamos mais a utilizá-lo, e quaisquer instâncias encontradas deveriam ser removidas/substituídas por 'obsoleta'.

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.

Conversely, an item is no longer experimental when:

It is implemented in two or more major browsers; or
Its defining spec is stable and unlikely to change.

Páginas arquivadas

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.

Quando é que uma página deverá ser arquivada?

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.

Páginas eliminadas

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.

Quando é que uma página deverá ser eliminada?

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.

Quando documentar novas tecnologias

On MDN, 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 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 the docs 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."

You should definitely 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.), which has reached a reasonable level of stability (e.g. a W3C working draft or candidate recommendation, or the spec is looking to be fairly stable judging by the flow of issues filed against it).
It is implemented consistently in at least one browser, with other browser developers showing signs of interest (such as an active ticket or "intent to implement" process in effect).

You should be more wary of documenting a new technology (but should still consider it if it makes sense) if it:

Doesn't have a spec, or the spec is a rough note that looks liable to change.
One or zero browsers currently implement 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, looking at browser bug trackers and mailing lists, etc.).

You should not consider documenting a new technology if it:

Is not a web-exposed technology and/or is completely proprietary.
Is already showing signs of being deprecated, or superseded by a similar feature.

Convenções

Quando é removido algo da especificação

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 {{domxref("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 Browser Compatibility Data repository's JSON files contain data for the removed items, delete those objects from the JSON code and submit a PR with that change, explaining why in the commit message and the PR description. Be careful to check that you don't break the JSON syntax while doing this.
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 {{domxref("RTCPeerConnection.close()")}}), add the {{TemplateLink("obsolete_header")}} macro to the top of the page and add the {{tag("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 {{TemplateLink("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.
- Update any relevant entries in the Browser Compatibility Data repo to reflect the obsolescence of the item(s) affected.
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 {{domxref("RTCPeerConnection.close()")}}), add the {{TemplateLink("deprecated_header")}} macro to the top of the page and add the {{tag("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 {{TemplateLink("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.
- Update any relevant entries in the Browser Compatibility Data repo to reflect the deprecation of the item(s) affected.

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 Web Docs chat room on Matrix, or on the MDN Web Docs discussion forum.

Copiar conteúdo dentro da 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 {{TemplateLink("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).

Copiar conteúdo de outro lado

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.