Collegamenti a Termini del Glossario e Tooltip: Regole di Scrittura

Un collegamento a termine del glossario connette un termine alla sua prima menzione significativa all’unica pagina che possiede la sua definizione completa. Il collegamento aiuta il lettore a risolvere un linguaggio sconosciuto senza interrompere l’articolo e fornisce ai crawler una relazione coerente tra il termine e la sua pagina entità canonica.

Un URL canonico è la versione preferita di una pagina quando più URL contengono lo stesso contenuto o contenuti sostanzialmente simili.

Quella frase è l’elemento reale. L’ancora è il termine esatto, la destinazione è la sua voce di glossario canonica e la frase circostante rimane comprensibile senza aprire il collegamento. Sui sistemi che lo supportano, lo stesso collegamento può mostrare un breve tooltip informativo al passaggio del mouse o al focus da tastiera. La pagina collegata — non il tooltip — rimane la fonte di verità.

Perché questo elemento è importante

I lettori non arrivano con lo stesso vocabolario. Uno specialista può riconoscere “URL canonico” immediatamente, mentre un acquirente o un nuovo membro del team potrebbe aver bisogno di una definizione. Spiegare ogni termine tra parentesi rallenta la prosa per esperti; non spiegarne nessuno esclude i nuovi arrivati. Un collegamento a termine del glossario crea un discreto portello di fuga: continua se il termine ti è familiare o apri la sua definizione se non lo è.

La regola della prima menzione è importante perché l’incertezza si accumula. Se un lettore fraintende un termine nel secondo paragrafo, ogni affermazione successiva basata su quel termine è più difficile da valutare. Collegare la prima occorrenza significativa risolve l’incertezza prima che si diffonda. La regola non significa “collega la prima corrispondenza di stringa.” Un termine in un titolo, etichetta di navigazione, esempio di codice o teaser potrebbe non avere ancora il significato usato nella spiegazione.

L’estraibilità automatica è la capacità del software di preservare una relazione dopo che la presentazione è stata rimossa. Un’ancora descrittiva e una destinazione stabile creano un arco esplicito: questa pagina usa il concetto e quella pagina di glossario lo definisce. Archi coerenti rafforzano quale URL possiede la definizione. Non creano un grafo di conoscenza formale né garantiscono visibilità, ma riducono l’ambiguità che un crawler dovrebbe altrimenti risolvere solo dalla prossimità.

L’eccesso di collegamenti annulla questi benefici. Quando ogni termine ripetuto è collegato, la pagina smette di segnalare priorità. I lettori affrontano un campo di uscite concorrenti, gli utenti di tecnologie assistive sentono la stessa destinazione ripetutamente e i motori ricevono molti archi ridondanti invece di un piccolo insieme di relazioni deliberate. Un collegamento canonico alla prima menzione significativa è quindi l’impostazione predefinita, non un minimo da ripetere in ogni sezione.

Quando usarlo

Usa l’elemento quando tutte e tre le condizioni sono vere:

1. Il termine ha una pagina di glossario canonica, non diverse definizioni quasi duplicate.
2. Comprendere il termine aiuta materialmente il lettore a comprendere la pagina corrente.
3. Il primo uso significativo può portare un’ancora descrittiva senza distorcere la frase.

I candidati ideali includono terminologia specialistica, acronimi al loro primo uso esteso, norme denominate, metriche e parole il cui significato nel dominio differisce dall’uso quotidiano. Un tooltip può anticipare una breve definizione; la pagina di glossario completa gestisce confini, esempi, fonti e termini correlati.

I casi limite sono dove l’elemento viene più spesso usato male:

• Vocabolario ordinario: non collegare una parola familiare solo perché esiste una voce di glossario.
• Menzioni incidentali: se l’articolo nomina un concetto ma non si basa su di esso, un collegamento crea un’uscita non necessaria.
• Menzioni ripetute: dopo il primo uso collegato, lascia il termine come testo a meno che una pagina lunga e multi-parte non crei un contesto di lettura genuinamente indipendente.
• Testo ancora ambiguo: “questo approccio,” “scopri di più” e “la metrica” non identificano l’entità del glossario. Collega il termine stesso.
• Nessuna destinazione canonica: non sostituire con un risultato di ricerca, archivio di tag o articolo vagamente correlato. Usa prosa semplice finché la definizione canonica non esiste.
• Definizione già fornita per intero: se il glossario non aggiunge profondità utile, un secondo deviazione definitoria potrebbe essere superflua.
• Instradamento commerciale: un collegamento al glossario non è una call to action mascherata per un prodotto. Pagine prodotto, flussi di registrazione e pagine di prezzi servono intenti di lettura diversi.

Applica le regole di scrittura degli elementi condivise prima di improvvisare. La loro regola di precedenza richiede agli autori di selezionare un elemento in base allo scopo. Se lo scopo è connettere un termine nominato alla sua definizione canonica, usa questa relazione tipizzata piuttosto che un generico collegamento in linea stilato in modo simile.

Dove posizionarlo

Posiziona il collegamento sulla prima menzione significativa in prosa: la prima frase che usa il concetto nel senso della destinazione. Se il termine appare prima nel titolo o in un H2, collega il suo primo uso nel paragrafo successivo. Le intestazioni dovrebbero rimanere etichette di sezione stabili piuttosto che grandi bersagli di navigazione.

Per un acronimo, scrivi il termine completo seguito dall’abbreviazione e collega il termine completo: retrieval-augmented generation (RAG). Le occorrenze successive possono usare RAG senza collegamento.

Non posizionare un collegamento a termine del glossario:

• all’interno di un altro collegamento, pulsante o card cliccabile;
• accanto a un secondo collegamento sullo stesso testo ancora;
• in codice, un URL, un indirizzo email o testo letterale inserito dall’utente;
• in un’intestazione solo per soddisfare la regola della prima menzione;
• in ogni riga di una tabella quando una definizione collegata nell’introduzione può stabilire il termine;
• immediatamente accanto a un indicatore di citazione se i due bersagli diventano visivamente o operativamente indistinguibili;
• all’interno di un trigger di tooltip separato dal collegamento effettivo.

Se una frase contiene diversi termini sconosciuti, collega solo i termini necessari per comprendere quella frase. Tre o più collegamenti al glossario in una frase sono un avvertimento che la prosa presuppone troppo vocabolario. Riscrivi la frase, definisci un concetto sul posto o dividi la spiegazione prima di aggiungere altre uscite.

Anatomia

Il campione etichettato ha sei regioni:

1. Ancora del termine: il termine visibile o il nome esteso completo, senza “scopri di più.”
2. Destinazione canonica: un URL di glossario stabile che possiede la definizione.
3. Frase di contesto: sufficiente prosa per capire perché il termine appare, anche se il collegamento non viene aperto.
4. Stile del collegamento: il trattamento standard del collegamento in linea del sito; il colore non è l’unico indizio.
5. Indicatore di focus: uno stato visibile da tastiera che non viene tagliato dal paragrafo o dal tooltip.
6. Tooltip opzionale: un’anteprima breve legata al collegamento stesso, mai un controllo separato basato solo su icone.

La presentazione può cambiare senza modificare l’ancora, la destinazione o il comportamento della prima menzione.

Esempi di design

Ogni variante preserva lo stesso collegamento semantico.

Collegamento in linea predefinito: la base richiesta. Funziona con JavaScript disabilitato, in modalità lettura, nelle annotazioni di stampa e su dispositivi senza hover.

Tooltip di definizione al focus o hover: un miglioramento per contenuti educativi densi. L’anteprima è di una o due frasi e non contiene mai collegamenti, pulsanti, citazioni o controlli di formattazione.

Mobile e touch: il primo tocco segue il collegamento a meno che il prodotto non abbia un pattern di divulgazione consolidato e accessibile. Non far scoprire agli utenti che un tocco apre un’anteprima e un secondo tocco naviga, a meno che questa interazione non sia coerente su tutto il sito e chiaramente comunicata.

Sfondo scuro: collegamento, anello di focus, testo del tooltip e bordo del tooltip mantengono un contrasto chiaro. Non rimuovere la sottolineatura solo perché il colore d’accento è brillante.

Parametri

L’URL canonico e l’ancora visibile sono decisioni di contenuto. Il comportamento del tooltip appartiene al renderer. Separare queste fonti impedisce a una caratteristica interfaccia opzionale di cambiare il significato del collegamento.

Non inferire mai href da term: gli omonimi possono condividere l’ortografia richiedendo destinazioni diverse. Estrai un tooltip dal record del glossario solo quando la sua definizione breve è stata revisionata per l’uso al di fuori della pagina.

Sintassi ed esempi di codice

Tutti e tre i formati preservano un normale collegamento come nucleo. I campi nominati sono un contratto portabile; una piattaforma può renderizzarli con un blocco nativo, plugin o fase di pre-elaborazione.

Direttiva Markdown portabile

The :::glossary-link{href="/glossary/canonical-url/" definition="A canonical URL is the preferred version of a page when duplicate or similar URLs exist." tooltip="true"}canonical URL::: consolidates signals on the preferred page.

Se la pipeline di pubblicazione non supporta direttive in linea, usa Markdown ordinario e ometti il tooltip:

The [canonical URL](/glossary/canonical-url/) consolidates signals on the preferred page.

Shortcode Hugo

The {{< glossary-term-link href="/glossary/canonical-url/" definition="A canonical URL is the preferred version of a page when duplicate or similar URLs exist." tooltip="true" >}}canonical URL{{< /glossary-term-link >}} consolidates signals on the preferred page.

Questa notazione specifica la mappatura richiesta; non richiede che gli autori introducano un nuovo shortcode in un progetto che già gestisce i collegamenti al glossario tramite rendering Markdown o pre-elaborazione dei contenuti. Il fallback renderizzato deve sempre essere un normale elemento <a href>.

WordPress

<!-- wp:amicited/glossary-link {"href":"/glossary/canonical-url/","definition":"A canonical URL is the preferred version of a page when duplicate or similar URLs exist.","tooltip":true} -->
<a href="/glossary/canonical-url/">canonical URL</a>
<!-- /wp:amicited/glossary-link -->

Il contenuto esportato deve mantenere l’ancora e href anche quando i metadati del tooltip non sono disponibili.

Esempi

Buono

Seleziona un URL canonico per pagine sostanzialmente simili in modo che i segnali di indicizzazione puntino alla versione preferita.

Nell’articolo renderizzato, “URL canonico” porta a /glossary/canonical-url/ a questo primo uso significativo. L’ancora nomina l’entità esattamente, la frase fornisce abbastanza contesto locale per continuare la lettura e le occorrenze successive rimangono testo semplice. Un lettore può scegliere se la definizione completa è necessaria.

Cattivo

Seleziona una pagina preferita per pagine simili. Il tuo URL canonico dovrebbe quindi fare riferimento all’URL canonico in ogni sezione.

Questo fallisce due volte. “Pagina preferita” è una formulazione correlata ma non il termine esatto che la destinazione definisce, quindi la relazione è meno esplicita. Ripetere il collegamento all’URL canonico in ogni sezione aggiunge uscite senza aggiungere significato. La correzione corretta è collegare “URL canonico” una volta al suo primo uso significativo e lasciare gli usi successivi non collegati.

Un altro pattern sbagliato è un’icona informativa dopo un termine non collegato. L’icona nasconde la destinazione ai lettori che scansionano il testo del collegamento, crea un piccolo bersaglio tattile e può separare il tooltip dalla relazione di glossario navigabile.

Schema markup e accessibilità

Un collegamento a termine del glossario non necessita di un tipo Schema.org autonomo. Rimane un collegamento all’interno dell’Article, TechArticle o WebPage che lo contiene. Non produrre markup DefinedTerm, mentions o about per ogni collegamento in linea; aggiungi tali relazioni solo attraverso un modello di dati coerente a livello di pagina giustificato dal contenuto visibile.

L’accessibilità inizia con un’ancora reale. Deve essere comprensibile nel contesto, distinguibile senza solo colore, raggiungibile da tastiera e visibilmente focalizzata. Le informazioni essenziali non possono esistere solo nel tooltip.

Se viene implementato un tooltip, associalo all’ancora usando aria-describedby mentre è visibile. Aprilo al focus da tastiera oltre che al passaggio del mouse, mantienilo aperto mentre il puntatore si sposta sopra il tooltip e consenti a Escape di chiuderlo senza spostare il focus. Non posizionare controlli focalizzabili all’interno di un tooltip. Non dipendere dall’attributo HTML title come interfaccia di definizione: i suoi tempi, presentazione, supporto tattile ed esposizione alle tecnologie assistive sono inconsistenti. Un title può essere supplementare, ma non è il nome accessibile, la descrizione o la definizione canonica.

Il collegamento deve navigare quando gli script falliscono. Sui dispositivi touch, favorisci la navigazione diretta rispetto all’imitazione dell’hover. Se il miglioramento non può soddisfare questi requisiti, pubblica il semplice collegamento.

Regole di scrittura

Collega il termine esatto o la sua forma completa non ambigua. Mantieni le ancore da una a otto parole e sotto 80 caratteri. Includi articoli come “un”, “una”, “il” o “la” solo quando fanno parte di un nome proprio. Non mettere in grassetto ogni ancora del glossario; lo stile di collegamento standard comunica già l’interattività e l’enfasi accumulata rende rumorosa la prosa tecnica.

Usa un collegamento al glossario per termine per pagina per impostazione predefinita. Un secondo collegamento è accettabile solo quando contenuti consumati in modo indipendente — come un lungo appendice, una risposta FAQ autonoma o un modulo incorporato — perderebbero altrimenti la relazione. Non impostare un numero minimo fisso di collegamenti al glossario. Una pagina chiara con due termini necessari è meglio di una pagina con dieci uscite decorative.

Le definizioni dei tooltip dovrebbero essere di 40–180 caratteri e non più di due frasi. Dichiara cos’è il termine, non perché il lettore dovrebbe cliccare. Usa un linguaggio neutro e dichiarativo. L’anteprima deve concordare con la definizione corrente della destinazione e dovrebbe essere presa dal record del glossario quando possibile, in modo che gli aggiornamenti non divergano.

Non inserire mai questi elementi all’interno del collegamento o del tooltip:

• un altro collegamento, pulsante, controllo di modulo o icona interattiva;
• un’affermazione commerciale o call to action;
• un elenco di citazioni o nota bibliografica;
• un’immagine, video, tabella, blocco di codice o procedura multi-step;
• una definizione che entra in conflitto o si espande oltre la pagina canonica;
• istruzioni essenziali per completare il compito del lettore.

Rivedi gli omonimi manualmente. “Java,” “conversion” o “agent” possono nominare entità diverse. La frase e la destinazione devono risolvere lo stesso significato. Non ruotare mai le destinazioni per distribuire collegamenti; la canonicità è il punto.

Tipi di post che lo usano

Il frontmatter postTypes[] identifica i formati per cui questo elemento è una parte documentata del sistema di contenuti. La tabella indica come ogni formato applica lo stesso contratto della prima menzione.

Checklist QA

• Destinazione canonica: il percorso è l’unica pagina di glossario che possiede la definizione; non è un URL di ricerca, tag, prodotto o articolo correlato.
• Destinazione esistente: il file di contenuto esiste ora o il percorso appare nel registro canonico approvato per la stessa release.
• Significato corrispondente: l’ancora e la destinazione si riferiscono allo stesso senso del termine, inclusi acronimi ambigui e omonimi.
• Prima menzione significativa: il collegamento appare in prosa prima degli usi successivi, non in un’intestazione o esempio di codice solo perché quell’occorrenza è venuta prima nell’ordine sorgente.
• Ancora esatta: le parole collegate nominano il termine o la sua forma completa non ambigua; non c’è “clicca qui” o sostituto vago.
• Frase locale funzionante: un lettore può capire la frase senza aprire la destinazione o attivare il tooltip.
• Predefinito uno per termine: le occorrenze ripetute rimangono non collegate a meno che un contesto di lettura indipendente documentato non giustifichi un altro collegamento.
• Nessun grappolo di collegamenti: la frase e il paragrafo rimangono leggibili; i termini sconosciuti eccessivi vengono riscritti piuttosto che coperti con collegamenti.
• Parità del tooltip: qualsiasi anteprima concorda con la definizione canonica e rimane entro 40–180 caratteri.
• Miglioramento progressivo: l’ancora funziona ancora quando script, hover o stili del tooltip non sono disponibili.
• Comportamento da tastiera: il focus è visibile; il tooltip appare al focus, può essere chiuso con Escape e non contiene controlli focalizzabili.
• Comportamento tattile: il collegamento ha una dimensione normale del bersaglio e non richiede hover o un’interazione inspiegabile a due tocchi.
• Moderazione dei dati strutturati: nessuna relazione schema non supportata o tipo di elemento inventato viene emessa.
• Output portabile: Markdown, Hugo e WordPress preservano lo stesso termine e href canonico anche se i metadati del tooltip vengono rimossi.
• Stato screenshot: i commenti di cattura rimangono istruzioni non renderizzate finché gli asset nominati non esistono; nessuna immagine inesistente viene referenziata.

FAQ

Il template dell’academy renderizza le domande del frontmatter revisionate che coprono idoneità, prima menzione, ambito del tooltip, coerenza canonica e limiti dei collegamenti.