Como etiquetar devidamente as páginas
As tags de artigo são uma maneira importante de colocar os visitantes em contacto com conteúdo útil. Cada página normalmente deverá ter várias tags para ajudar a manter o conteúdo organizado. Esta página explica a melhor maneira para etiquetar as páginas, e assim os nossos leitores podem encontrar a informação e nós podemos manter-nos organizados.
Para obter ajuda com a interface do utilizador para editar tags, consulte a secção de etiquetagem no nosso guia do editor.
Por favor, utilize as tags devidamente como explicado em baixo. Se não o fizer, as nossas ferramentas automatizadas não irão gerar corretamente as listas de conteúdo, as páginas de destino, e ligação dos artigos.
As tags são utilizadas de vários modos na MDN:
- Categorização do documento
- What type of document is it? Is it a reference? A tutorial? A landing page? Our visitors can use these tags to filter searches, so they're really important!
- Identificação do tópico
- What is the article about? Is it about an API? The DOM? Graphics? Again, these tags are important because they can filter searches.
- Estado da tecnologia
- What's the status of the technology? Is it non-standard? Obsolete or deprecated? Experimental?
- Nível de proficiência
- For tutorials and guides, how advanced is the material covered by the article?
- Metadados do documento
- The writing community uses tags to keep track of which pages need what kind of work.
Here's a quick guide to the types of tags and possible values for them.
When you tag an article with one of these categories, you help the automated tools more accurately generate landing pages, tables of contents, and so on. Our new search system will also use these terms so that our visitors can locate reference or guide information at will.
We use the following category names as standard tagging terms:
- The article provides introductory material about a topic. Ideally each technology area should have only one "Intro".
- The article is critical and will display prominently on landing pages. Use this tag sparingly (never more than three documents in each documentation area).
- The article contains reference material about an API, element, attribute, property, or the like.
- The page is a landing page.
- The article is a how-to or guide page.
- The article is a code sample page, or has code samples (that is, actual snippets of useful code, not one-line "syntax examples").
By identifying the article's topic area, you are helping generate better search results (and landing pages and navigation as well).
While there's some room for flexibility here as we identify new topic areas, we try to limit ourselves to the names of APIs or technologies. Some useful examples:
APIfor each interface, method and property.
Methodfor each method of an API
Propertyfor each property of an API
WebExtensionsfor WebExtension documentation.
In general, your topic identification tag should be the name of an interface with a number of related pages (like Node, which has many pages for its various properties and methods), or the name of an overall technology type. You might tag a page about WebGL with
WebGL, for example, but a page about <canvas> (en-US) with
Conteúdo específico da Mozilla
Estas tags são utilizadas apenas no conteúdo especifico da Mozilla:
Within the API reference, each article should identify which part of the API it covers:
- The main article for an interface should have this tag. For example,
- Each interface may have up to one page tagged "Constructor"; this is the interface's constructor. The page should have the same name as the interface, like
- Every article describing a particular property within an interface needs this tag. See
RTCPeerConnection.connectionState(en-US), for example.
- Each article documenting an interface method needs this tag. See
RTCPeerConnection.createOffer()(en-US) for example.
In addition, the reference pages need to include interface, property, and method names among their tags. Some examples:
- The interface
- Include the tag "RTCPeerConnection" along with the other relevant tags ("Interface", "WebRTC", "WebRTC API", "API", "Reference", and so forth).
- The method
- Include the tags "RTCPeerConnection" and "createOffer" (note no parentheses in tag names!) along with the other relevant tags, including "WebRTC", "WebRTC API", "API", "Reference", and so forth. Consider including things like "Offer" and "SDP", which are also relevant here.
- The property
- Include the tags "RTCPeerConnection" and "iceConnectionState" along with the other relevant tags, including "WebRTC", "WebRTC API", "API" and "Reference". Also consider including "ICE".
To help the reader understand how viable a technology is, we use tags to label pages as to the status of the technology's specification. This isn't as detailed as actually explaining what the spec is and how far the technology has come in the specification process (that's what the Specifications table is for), but it helps the reader judge, at a glance, whether it's a good idea to use the technology described in the article.
Here are possible values for these tags:
- Apply this tag to reference pages which describe a property or attribute which is read-only.
- Indicates that the technology or API described on the page is not part of a standard, whether it's stable or not in any browsers which implement it (if it's not stable, it should also be Experimental). If you don't use this tag, your readers will assume the technology is standard. The compatibility table on the page should clarify which browser(s) support this technology or API.
- The technology or API covered on the page is marked as deprecated in the specification, and is likely to eventually be removed, but is generally still available in current versions of browsers.
- The technology or API has been deemed obsolete and has been removed (or is actively being removed) from all or most current browsers.
- The technology is not standardized, and is an experimental technology or API that may or may not ever become part of a standard. It is also subject to change in the browser engine (typically only one) that implements it. If the technology isn't part of any specification (even in draft form), it should also have the Non-standard tag.
- The API requires privileged access to the device on which the code is running.
- The API only works in certified code.
These tags are no excuse to leave out the compatibility table in your article! That should always be present.
Use the skill-level tag type only for guides and tutorials (that is, pages tagged
Guide) to help users choose tutorials based on how familiar they are with a technology. There are three values for this:
- Articles designed to introduce the reader to a technology they've never used or have only a passing familiarity with.
- Articles for users who have gotten started with the technology but aren't experts.
- Articles about stretching the capabilities of a technology and of the reader.
The writing community uses tags to label articles as requiring specific types of work. Here's a list of the ones we use most:
- The article is not complete, and is at least in theory still actively being updated (although it's also possible it's been forgotten about). Try to check with the most recent contributors before making changes, in order to avoid potential content collisions.
- The article needs a table to specify compatibility of a feature across browsers. See here for a guide on contributing to browser compatibility.
- The article is a stub, or is otherwise lacking information. This tag means that someone should review the content and add more details and/or finish writing the article.
- The article needs one or more examples created to help illustrate the article's point. These examples should use the live sample system.
- The article has one or more examples that need to be updated to use the live sample system.
- The article needs a table to indicate on which specification document(s) the feature was defined.
- The content is out of date and needs to be updated.
- The content is not really worth localizing and will not appear on localization status pages.
- The content is important and should be marked as a priority for MDN translators. Shows up in an extra priority table on localization status pages.
Portanto, para cada página que atribui tags de vários tipos de tag, por exemplo:
- A tutorial about WebGL for beginners
- Reference page for <canvas> (en-US)
- A landing page for Firefox OS developer tools
Search filters won't work properly unless we tag MDN pages properly. Here's a table of search filters and which tags they look for.
Nota: If multiple tags are listed under "Tag name," that means any one or more of these tags must be present for the article to match.
|Grupo de filtro||Nome do filtro de pesquisa||Nome da tag|
|Tópico||APIs and DOM||API || DOM|
|Add-ons & Extensions||Add-ons || Extensions || Plugins || Themes || WebExtensions|
|Firefox OS||Firefox OS|
|Open Web Apps||Apps|
|Web Development||Web Development|
|Writing Documentation||MDN Meta|
|Skill level||I'm an Expert||Advanced|
|Tipo de documento||Docs||This restricts the search to docs content, leaving out Hacks and other MDN content.|
|Demos||This includes Demo Studio content in the search results.|
|How-To & Tutorial||Guide|
|Developer Profiles||This includes developer profiles from the MDN site in the search results.|
|External Resources||The dev team is still figuring this out...|
There are several kinds of tag problems you can help fix:
- No tags
- Generally articles should have at least a "category" tag and a "topic" tag. Usually other tags are appropriate as well, but if you can help us ensure that the minimum tags are present, you'll be a documentation hero!
- Tags that don't follow our tagging standards
- Please fix any documents whose tags don't follow the standards on this page.
Note that you may occasionally see some localized tags (such as
Référence) showing up on some English pages. This was due to a bug in Kuma, which caused the tags to reappear even if they were deleted. That bug has since been fixed, so any remaining localized tags can be cleaned up if they're spotted.
- Incorrect tags
- Missing tags
- Tag spam
- This insidious beast is the most revolting tag problem of all: some Web vermin has deposited its droppings in the page tags (like "Free warez!" or "Hey I was browsing your site and wanted to ask you if you could help me solve this problem I'm having with Flash crashing all the time"). We've got to delete these right away! They're ugly, they're hard to manage if they're allowed to linger too long, and they're terrible for SEO.
If you see one (or more) of these problems, please log into MDN and click EDIT at the top right of the MDN window. Once the editor loads up, scroll down to the bottom of the page, where you'll see the tag box. For more details on the tagging interface, see "The tags box" in the MDN editor guide.