Usare correttamente i tag

I tag associati agli articoli sono uno strumento fondamentale per permettere ai visitatori di accedere a contenuti rilevanti. Normalmente, ogni pagina dovrebbe essere associata a più tag, che contribuiscono a mantenere i contenuti organizzati. Questa pagina spiega come ottimizzare l'uso dei tag per facilitare i lettori nella ricerca e agevolare i gestori nell'organizzazione e mantenimento dei contenuti.

Per informazioni su come modificare i tag dall'interfaccia utente, consulta la sezione sui tag della guida all'editor di testo di MDN.

È importante utilizzare i tag secondo queste regole, altrimenti gli automatismi non saranno in grado di generare liste di contenuti, landing page e link incrociati tra i vari articoli.

Nota per i traduttori e i localizzatori: non tradurre nessuno dei tag elencati in questa pagina. Sono necessari per scopi specifici, come ad esempio operazioni di gestione del sito ed elaborazione automatica di dati. Tali processi non funzionano con tag tradotti.

Uso dei tag in MDN

In MDN i tag vengono utilizzati in diversi modi:

Categoria documento
Di che tipo di documento si tratta? È un materiale di consultazione? Un tutorial? Una landing page? Si tratta di una categoria di tag fondamentali, che i lettori possono utilizzare per filtrare le ricerche.
Argomento
Qual è l'argomento dell'articolo? Parla di API? Oppure di DOM? O di grafica? Questi tag, al pari dei precedenti, hanno un ruolo fondamentale nel filtrare i risultati di ricerca.
Identificazione API
Ogni pagina di consultazione di un'API deve essere associata a un tag che identifichi lo specifico componente trattato (ovvero l'interfaccia di cui fa parte e, dove applicabile, la proprietà o metodo).
Stato tecnologia
Qual è lo stato dell'arte della tecnologia trattata? Non è riconosciuta come standard? È obsoleta o deprecata? Oppure sperimentale?
Livello di competenza
Applicabile a tutorial e guide: quanto è avanzata la materia di cui tratta l'articolo?
Metadati del documento
Chi scrive e gestisce i contenuti usa questi tag per tenere traccia del tipo di interventi da effettuare sulle pagine.

Guida ai tipi di tag

Segue una breve guida ai tipi di tag utilizzati su MDN e i loro significati.

Categoria documento

I tag di categoria, associati a un articolo, facilitano la generazione automatica di landing page, indici e via dicendo. Inoltre, nel nuovo sistema di ricerca, questi termini possono essere usati anche dagli utenti per trovare materiali di consultazione e guide pertinenti.

Ecco i tag che identificano le categorie:

"Introduzione". L'articolo tratta di contenuti introduttivi su un argomento. Come regola generale, ciascuna area tecnologica dovrebbe disporre di un unico tag "Intro".
"Consultazione". L'articolo contiene materiali di consultazione su un'API, un elemento, un attributo, una proprietà o simili.
Indica che la pagina in questione è una landing page, la pagina iniziale di un dato argomento.
"Guida". L'articolo consiste in una pagina contenente una guida o una procedura guidata.
"Esempio". L'articolo contiene un codice di esempio, oppure campioni di codice (ovvero non semplici esempi di sintassi da una riga, bensì frammenti di codice che possono essere riutilizzati).

Argomento

I tag che identificano l'argomento di un articolo consentono di ottenere risultati di ricerca più pertinenti. Inoltre, facilitano la navigazione e l'individuazione di landing page.

Pur trattandosi di una categoria che può espandersi mano a mano che vengono identificati nuovi argomenti, cerchiamo di limitare i tag ai nomi di API o tecnologie. Alcuni esempi pratici:

In linea generale, i tag di argomento sono nomi di un'interfaccia associati a diverse pagine rilevanti (per esempio, Node è associato a diverse pagine perché possiede molteplici proprietà e metodi), o nomi che indicano un complesso di tecnologie. Ad esempio, una pagina che parla di WebGL potrebbe essere associata ai tag Graphics e WebGL, mentre una pagina che tratta dell'elemento <canvas> ai tag HTML, Element, Canvas e Graphics.

Contenuti Mozilla

I seguenti tag sono associati esclusivamente a contenuti specifici di Mozilla:

Identificazione API

All'interno del materiale di consultazione delle API, ciascun articolo dovrebbe essere associato a un tag che identifichi la specifica parte dell'API trattata:

"Interfaccia". Il tag da associare all'articolo principale dell'interfaccia. Esempio: RTCPeerConnection.
"Costruttore". Ciascuna interfaccia può contenere fino a una pagina con tag "Constructor", ovvero il costruttore dell'interfaccia. Il titolo della pagina deve corrispondere al nome dell'interfaccia. Esempio: RTCPeerConnection().
"Proprietà". Questo tag va associato a ciascun articolo che descrive una proprietà specifica all'interno dell'interfaccia. Esempio: RTCPeerConnection.connectionState
"Metodo". Questo tag va associato a ciascun articolo che descrive un metodo dell'interfaccia. Esempio: RTCPeerConnection.createOffer()

In aggiunta, le pagine di consultazione devono includere tra i tag i nomi di interfaccia, proprietà e metodo. Alcuni esempi:

L'interfaccia RTCPeerConnection
include il tag in aggiunta ad altri tag rilevanti come , , , , ecc.
Il metodo RTCPeerConnection.createOffer()
include i tag e (attenzione: non inserire parentesi all'interno dei nomi dei tag!) in aggiunta ad altri tag rilevanti come , , , , , ecc. Qui è anche possibile aggiungere anche altri tag rilevanti come e .
La proprietà RTCPeerConnection.iceConnectionState
include i tag e in aggiunta ad altri tag rilevanti come , , , e . È possibile aggiungere anche il tag .

Stato tecnologia

I seguenti tag identificano lo stato dell'arte delle specifiche tecnologiche. Aiutano il lettore a farsi un'idea di quanto praticabile sia una particolare tecnologia. Il tag non spiega in dettaglio il tipo e i progressi della tecnologia nel processo di specificazione (per questo scopo c'è la tabella delle specifiche), ma aiuta il lettore a giudicare a colpo d'occhio quanto convenga utilizzare la tecnologia descritta nell'articolo.

Di seguito, i possibili valori per questa categoria di tag:

"Sola lettura". Il tag da applicare alle pagine di consultazione, che descrivono una proprietà o un attributo di sola lettura.
"Non standardizzata". Indica che la tecnologia o l'API descritta sulla pagina non rientra in alcuno standard, indipendentemente dalla sua stabilità nei browser che la implementano (se è instabile, va aggiunto anche il tag ). In assenza di questo tag, il lettore presumerà che quella descritta sia una tecnologia standard. La pagina deve inoltre contenere una tabella di compatibilità con l'elenco dei browser che supportano l'API o la tecnologia trattata.
"Deprecata". Quando la tecnologia o API trattata nella pagina è segnalata come "deprecata", è probabile che cada in disuso, anche se per il momento è ancora disponibile nelle versioni più recenti dei browser.
"Obsoleta". La tecnologia o API trattata è ormai ritenuta obsoleta, dunque è stata rimossa (o è in corso di rimozione) da tutti gli attuali browser, o quasi.
"Sperimentale". La pagina tratta di una tecnologia non ancora standardizzata, dunque sperimentale, oppure di un'API che potrebbe o meno diventare parte di uno standard. È inoltre soggetta alle modifiche nel motore del browser che la implementa (di solito si tratta di un singolo browser). Se tale tecnologia non fa parte di alcuna specifica (neanche in forma di bozza), deve essere associata anche al tag .
"Richiede privilegi". L'API trattata richiede privilegi di accesso al dispositivo su cui si esegue il codice.
"Solo certificato". L'API trattata funziona solo con codice certificato.

I tag precedenti non sostituiscono la tabella di compatibilità, che deve essere sempre presente nell'articolo.

Livello di competenza

I tag che indicano il livello di competenza vanno applicati unicamente a guide e tutorial (ovvero, alle pagine con tag Guide). Aiutano l'utente a scegliere un tutorial in base alla propria conoscenza di una data tecnologia. Questa categoria ha tre valori:

"Principiante". Articoli concepiti per presentare una tecnologia a chi non l'ha mai utilizzata o la conosce solo superficialmente.
"Intermedio". Articoli destinati a utenti che hanno già iniziato a utilizzare la tecnologia trattata, ma non ne sono ancora esperti.
"Avanzato". Articoli che approfondiscono le possibilità della tecnologia trattata e mettono alla prova le competenze dell'utente.

Metadati del documento

La comunità dei creatori di contenuti usa i tag per contrassegnare gli articoli che richiedono interventi di tipo specifico. Di seguito, una lista dei più utilizzati:

"Bozza". L'articolo non è ancora completo. In teoria, significa che è in fase di aggiornamento, ma potrebbe trattarsi anche di un articolo abbandonato. Prima di eseguire qualsiasi modifica, è buona norma contattare i collaboratori che hanno lavorato all'ultima bozza dell'articolo, al fine di evitare possibili conflitti di contenuto.
"Richiede tabella compatibilità". Occorre aggiungere all'articolo una tabella che specifichi la compatibilità della funzione trattata con i vari browser. Vedi anche la guida per collaborare alla compilazione di una tabella di compatibilità dei browser.
"Richiede contenuti". L'articolo è solo un abbozzo, oppure contiene informazioni incomplete. Questo tag indica che è richiesto un revisore per controllare la correttezza dei contenuti, aggiungere ulteriori informazioni e/o completare la stesura dell'articolo.
"Richiede esempio". L'articolo necessita di uno o più esempi che chiariscano i concetti illustrati. Tali esempi devono utilizzare il sistema di codice esempio live.
"Richiede esempi live". L'articolo contiene uno o più esempi che devono essere aggiornati al sistema di codice esempio live.
"Richiede formattazione". Il codice di markup che costituisce la formattazione dell'articolo deve essere ottimizzato (solitamente perché l'articolo è formattato solo o quasi da tag generici tipo <p>).
"Richiede tabella specifiche". Occorre aggiungere all'articolo una tabella che documenti le specifiche della funzione trattata.
"Richiede aggiornamento". Occorre aggiornare i contenuti dell'articolo con informazioni più recenti.
"Escluso da localizzazione". Non vale la pena localizzare questo contenuto, dunque verrà escluso dalle pagine di stato della localizzazione.
"Priorità localizzazione". Questo contenuto è importante, i traduttori di MDN dovrebbero dargli la priorità rispetto ad altri articoli. Questo tag viene visualizzato in una tabella delle priorità a parte nelle pagine di stato della localizzazione.

Combinare i vari tag

Abbiamo visto che a ogni pagina vanno assegnati più tag di diverse categorie, per esempio:

Un tutorial per principianti su WebGL
comprende i tag , , ,
La pagina di consultazione dell'elemento <canvas>
comprende i , , , ,
Una landing page sugli strumenti di sviluppo di Firefox
comprende i tag , ,

Tag e filtri di ricerca

L'efficacia dei filtri di ricerca dipende dall'inserimento dei tag corretti nelle pagine di MDN. Di seguito, una tabella dei filtri di ricerca con i tag corrispondenti. (Questi filtri di ricerca si applicano unicamente al sito wiki (la versione modificabile di MDN); la versione MDN in sola lettura utilizza un sistema di ricerca diverso, senza filtri.)

Nota: Quando sotto la colonna "Nome tag" sono presenti più tag, significa che, perché l'articolo compaia nei risultati di ricerca, deve essere associato a uno o più dei tag elencati.

Gruppo filtro Nome filtro ricerca Nome tag
Argomento APIs and DOM ||
Add-ons & Extensions || || || ||
CSS
Canvas
Firefox
Firefox OS
Games
HTML
HTTP
JavaScript
Marketplace
MathML
Mobile
Open Web Apps
SVG
Web Development
Web Standards
WebExtensions
WebGL
Writing Documentation
XPCOM
XUL
Livello di competenza I'm an Expert
Intermediate
I'm Learning
Tipo di documento Docs Restringe il campo di ricerca alla documentazione, escludendo i contenuti di Hacks e contenuti di altro tipo in MDN.
Demos Questo tipo di documento non è più in uso nella documentazione web di MDN.
Tools
Code Samples
How-To & Tutorial
Developer Profiles Include nei risultati di ricerca i profili degli sviluppatori registrati su MDN.
External Resources Il team di sviluppo non ha ancora stabilito come utilizzare questo filtro...

Problemi di tag che puoi aiutare a risolvere

I collaboratori possono contribuire a risolvere diversi tipi di problemi riguardanti i tag:

Niente tag
Di norma, ogni articolo dovrebbe essere associato almeno a un tag per la categoria e a un tag per l'argomento del documento. È possibile aggiungere altri tag appropriati, ma assicurarsi che ogni pagina abbia i tag strettamente necessari costituisce già di per sé un enorme contributo.
Tag non conformi agli standard MDN
Quando si trova un documento che non segue gli standard di questa pagina, è opportuno correggerlo.
Attenzione: su alcune pagine in lingua inglese è possibile talvolta imbattersi in tag localizzati in altre lingue (es. Référence). Questo problema è dovuto a un bug in Kuma per cui i tag ricomparivano anche dopo essere stati eliminati. Il bug è stato successivamente risolto: ora è possibile ripulire le pagine da tutti i tag erratamente localizzati.
Tag non corretti
Se un articolo sul codice HTML è associato al tag "JavaScript", si tratta probabilmente di un errore. Lo stesso vale per un articolo che tratta di meccanismi interni di prodotti Mozilla, ma è associato al tag "Web". I tag non corretti vanno rimossi e quelli appropriati vanno aggiunti, se mancanti. Inoltre, vanno corretti anche i tag che contengono errori di battitura, come ad esempio "Javascript" (il tag funziona comunque, poichè il sistema non coglie la differenza tra maiuscole e minuscole, ma anche la forma va curata).
Tag mancanti
Un articolo potrebbe già essere associato ad alcuni tag, ma non a tutti quelli necessari. In questo caso, occorre aggiungere i tag mancanti. Per esempio, se una pagina di consultazione in JavaScript presenta soltanto il tag "JavaScript" (peraltro corretto), i collaboratori sono incoraggiati ad aggiungere i tag "Reference" o di un'altra categoria.
Tag spam
Si tratta del problema più fastidioso di tutti: alcuni malevoli frequentatori del Web hanno attaccato anche MDN, infestando le pagine con tag tipo "Free warez!" o "Ehi passavo da questo sito e volevo sapere se potete aiutarmi a risolvere il problema con Flash che crasha sempre". Questi tag vanno eliminati al più presto! Non solo danno fastidio e creano problemi nella gestione delle pagine se non vengono rimossi tempestivamente, ma hanno anche un effetto deleterio sul SEO.

Quando si nota uno (o più) di questi tag, accedere a MDN e premere MODIFICA nell'angolo in alto a destra della finestra. Una volta che l'editor si sarà caricato, scorrere fino al riquadro dei tag, che si trova in fondo alla pagina. Per ulteriori dettagli sull'interfaccia di inserimento dei tag, consulta la sezione sui tag nella guida all'editor di MDN.