Definition Box: Formato, Regole ed Esempi

Un definition box offre al termine principale della pagina una spiegazione esatta e circoscritta prima che l’articolo la sviluppi. È un elemento di apertura: un componente di contenuto riutilizzabile che appare all’inizio perché il lettore non dovrebbe dover dedurre il termine centrale da esempi, benefici o contesto.

Questo esempio dal vivo è l’elemento completo, non un’anteprima di una definizione più avanti nella pagina. Il suo titolo è facoltativo; il corpo no. Il contratto di produzione sottostante determina quando l’elemento è appropriato, cosa significa ogni campo e come lo stesso contenuto viene mappato tra i vari sistemi di pubblicazione.

Perché questo elemento è importante

I lettori raramente iniziano una pagina informativa leggendo ogni parola in ordine. Scansionano il titolo, le righe di apertura, le intestazioni e i blocchi visivamente distinti per decidere se la pagina risponde alla loro domanda. Una definizione sepolta in un paragrafo introduttivo costringe il lettore a separare la risposta dal contesto, dalle affermazioni e dall’ambientazione. Il box elimina questo lavoro: il suo confine dice «questa è la definizione».

Questo confine dà anche alla definizione una posizione stabile e indirizzabile. I redattori sanno dove rivederla, i template sanno dove renderizzarla e le revisioni future non costringono un lettore o un controllo qualità a cercare in vari paragrafi di apertura. Un posizionamento coerente è importante in una libreria perché lo stesso compito informativo non dovrebbe spostarsi in modo imprevedibile da pagina a pagina.

L’estraibilità automatica è la capacità del software di isolare un’unità di contenuto senza perderne il significato. Una definizione tipizzata con titolo e corpo può essere indicizzata, confrontata, citata o trasformata in modo indipendente. Una frase che semplicemente definisce un termine all’interno del testo libero si dissolve nella prosa circostante: il software deve indovinare dove inizia la definizione, dove finisce e se l’affermazione precedente ne fa parte. Segui le regole di scrittura degli elementi in modo che l’identità semantica sopravviva anche quando il design visivo cambia.

La formulazione deve comunque funzionare senza il box. Lo stile crea contrasto per le persone; un soggetto, verbo e significato distintivo autonomi creano estraibilità per le macchine. «È un metodo per migliorarli» fallisce quando viene rimosso dal suo paragrafo. «Il content pruning è il processo di rimozione, consolidamento o aggiornamento di pagine che non servono più a uno scopo utile di ricerca o commerciale» sopravvive.

Quando usarlo

Usa un definition box quando la pagina è organizzata attorno a un termine e quel termine può essere definito con precisione in una breve affermazione. È obbligatorio per i formati glossario e che-cos’è-X. È obbligatorio anche per i contenuti di tipo diagnostico o patologico: il lettore deve sapere cos’è la condizione nominata prima di considerare cause, test o rimedi.

Le pagine basate sui sintomi e le guide passo-passo usano raramente l’elemento. Aggiungilo solo quando una breve definizione risolve una reale ambiguità necessaria per l’attività. Ad esempio, una guida intitolata «Come risolvere la cannibalizzazione delle parole chiave» può definire la cannibalizzazione delle parole chiave prima dei passaggi perché la diagnosi determina quale soluzione applicare. Una guida intitolata «Come cambiare un title tag» non ha bisogno di un box che definisca un title tag se il pubblico e l’istruzione iniziale rendono già l’oggetto inequivocabile.

Non usare un definition box per:

• Un’introduzione generale, storia, dichiarazione di benefici o spiegazione del perché l’argomento è importante. Questi passaggi sviluppano l’articolo; non definiscono il termine.
• Un riassunto della pagina. Un riassunto raccoglie diverse conclusioni, mentre una definizione enuncia il significato di un termine.
• Una promessa di prodotto come «AmICited è il modo più semplice per migliorare la visibilità». Questa è un’argomentazione di posizionamento, non una definizione verificabile.
• Un avviso, avvertenza, prerequisito o suggerimento. Il suo compito comunicativo è diverso anche quando un tema potrebbe farlo sembrare lo stesso pannello colorato.
• Un termine secondario introdotto a metà articolo. Definisci quel termine nella frase in cui appare per la prima volta, o dagli una pagina propria quando merita un trattamento approfondito.
• Una citazione la cui autorità sostituisce la chiarezza. Attribuisci una definizione formale nella prosa circostante quando l’attribuzione è necessaria; mantieni il box leggibile come dichiarazione diretta.

L’errore comune più frequente è un’«introduzione alla definizione»: «Il churn dei clienti è uno dei concetti più importanti per le aziende in abbonamento, e comprenderlo può trasformare la crescita». Questo dice che il concetto è importante ma non dice mai cosa sia. Il box non può rendere precisa un’ambientazione vuota.

Dove posizionarlo

Il posizionamento codifica la priorità. Metti il definition box immediatamente dopo il paragrafo introduttivo o la breve introduzione, come primo blocco di contenuto. L’introduzione stabilisce perché il lettore è sulla pagina; il box fissa poi il significato prima che cause, esempi, benefici, passaggi o confronti dipendano da esso.

Non posizionare navigazione, indice dei contenuti, punti chiave, galleria di immagini o invito all’azione promozionale tra l’introduzione e la definizione. Questi blocchi costringono il lettore ad attraversare materiale non correlato prima di ricevere il significato del termine. Il breadcrumb e l’hero della pagina sono elementi cromati del template piuttosto che contenuti creati dall’autore, quindi possono precedere l’introduzione.

Usa un solo definition box per pagina. La regola esiste perché il componente identifica l’oggetto definitorio principale della pagina. Due box creano due termini principali in competizione e rendono ambigua l’estrazione. Se entrambi i termini sono veramente primari, dividi l’argomento in due pagine e collegale nella prosa. Se il secondo termine è subordinato, definiscilo inline invece di formattarlo come seconda risposta canonica.

Un blocco risposta diretta può coesistere con una definizione solo quando risponde a una domanda principale diversa. In una pagina diagnostica, la definizione può dichiarare cos’è la condizione mentre la risposta diretta indica la prima azione raccomandata. Quando la domanda principale della pagina è «Cos’è X?», la risposta diretta e la definizione sono la stessa risposta. Uniscile in un unico definition box; versioni adiacenti si limitano a ripetere la formulazione e competono per l’estrazione.

Anatomia

L’elemento ha due aree di creazione e una relazione strutturale. Lo screenshot deve mostrare l’elemento renderizzato senza incorporare testo esplicativo nell’immagine; la legenda sottostante rimane selezionabile, accessibile e manutenibile quando il design cambia.

Legenda renderizzata

1. Titolo facoltativo: Di solito «Cos’è X?» Identifica il termine esatto e non deve aggiungere una seconda affermazione.
2. Corpo obbligatorio: Una definizione autonoma che nomina il termine, lo colloca in una categoria utile e ne indica ciò che lo distingue.
3. Posizione di apertura: Il box segue l’introduzione e precede la prima sezione esplicativa. Questa relazione fa parte del contratto anche se non è un campo.

Bordo, sfondo, padding, trattamento delle icone e tipografia appartengono al renderizzatore. Gli autori forniscono il significato, non elementi visivi. L’elemento deve rimanere comprensibile se ogni stile decorativo viene rimosso.

Esempi di design

La galleria copre le varianti di contenuto supportate senza inventare diversi tipi semantici. Ogni cattura dovrebbe riutilizzare la stessa definizione quando possibile, in modo che i revisori possano valutare la gestione del titolo, l’impaginazione del corpo e il comportamento nel viewport invece di confrontare testi non correlati.

Con titolo: La variante preferita quando il termine è sconosciuto, ambiguo, abbreviato o diverso dal titolo esatto della pagina.

Senza titolo: Consentito quando l’intestazione della pagina e l’introduzione immediatamente precedente rendono il soggetto inequivocabile. Il corpo deve comunque nominare il termine; l’omissione del titolo non permette mai che pronomi come «esso» sostituiscano il soggetto.

Lunghezza massima: Il renderizzatore impagina l’intero corpo. Non deve troncare, comprimere, scrollare o ridurre il carattere per adattare il testo al massimo editoriale.

Viewport stretto: Titolo e corpo mantengono il loro ordine, la lunghezza di riga leggibile e il confine visibile. Nessun significato può dipendere da un’icona che si sposta accanto al testo.

Parametri

I parametri separano il contenuto dalla presentazione. I loro limiti mantengono le definizioni confrontabili tra pagine e impediscono al componente di trasformarsi in un callout generico.

Parametri del definition box

Il renderizzatore può derivare il termine per l’indicizzazione, ma gli autori non devono mai scrivere un corpo che dipenda dalla visualizzazione di quel campo derivato. Una definizione copiata deve nominare esplicitamente il suo soggetto.

Sintassi ed esempi di codice

Tutte e tre le forme portano lo stesso titolo e corpo. La direttiva Markdown portabile è la forma autoriale canonica; Hugo e WordPress sono adapter. Gli esempi usano deliberatamente una formulazione identica in modo che un test di migrazione possa confrontare i valori, non solo l’aspetto.

Direttiva Markdown portabile

:::definition
## Cos'è il content pruning?

Il content pruning è il processo di rimozione, consolidamento o aggiornamento di pagine che non servono più a uno scopo utile di ricerca o commerciale.
:::

La prima intestazione corrisponde a title; tutto ciò che segue corrisponde a body. Ometti l’intestazione per la variante senza titolo, ma mantieni il termine nel corpo.

Shortcode Hugo

{{< callout type="note" title="Cos'è il content pruning?" >}}Il content pruning è il processo di rimozione, consolidamento o aggiornamento di pagine che non servono più a uno scopo utile di ricerca o commerciale.{{< /callout >}}

Il sito riutilizza il renderizzatore di callout esistente per il trattamento visibile in Hugo. Il contratto di definizione deriva comunque dalla fonte portabile tipizzata: note qui è un adapter di rendering, non un permesso per inserire note ordinarie nei definition box.

Blocco o shortcode WordPress

[definition title="Cos'è il content pruning?"]Il content pruning è il processo di rimozione, consolidamento o aggiornamento di pagine che non servono più a uno scopo utile di ricerca o commerciale.[/definition]

Un’implementazione WordPress può esporre gli stessi campi come blocco personalizzato. I valori memorizzati rimangono title e body; i controlli dell’editor, i colori e la spaziatura sono impostazioni di presentazione e non devono alterare il significato della definizione.

Esempi

Questo è un buon esempio perché nomina il termine, identifica la condizione e indica la conseguenza distintiva. Non afferma che ogni coppia di pagine che condividono una parola sia in competizione; l’espressione «stessa intenzione di ricerca» fornisce il confine necessario. Il corpo è utile senza il titolo e abbastanza breve da essere citato integralmente.

Questo è un cattivo esempio perché non definisce mai la cannibalizzazione delle parole chiave. Offre importanza, pubblico, urgenza e un effetto vago, ma nessuna categoria o condizione distintiva. Sostituire «uno dei più importanti» con «una situazione in cui più pagine competono per la stessa intenzione di ricerca» trasforma la promozione in significato.

Un secondo schema errato è sovraccaricare il box: una definizione seguita da cause, cinque esempi, un avviso e uno strumento consigliato. Anche se la prima frase è accurata, il materiale extra distrugge il confine stabile. Mantieni la definizione; sposta cause ed esempi nella sezione successiva, l’avviso nel suo elemento corretto e il consiglio al punto in cui il lettore può agire.

Markup Schema e accessibilità

Un definition box non crea automaticamente un’entità Schema.org indipendente. In un articolo ordinario, il suo testo rimane parte dell’Article o TechArticle che lo contiene. In una pagina di glossario, un’implementazione editoriale può mappare il termine e la definizione su un vocabolario adatto solo quando il sito ha adottato quella politica di schema. Non inventare un tipo DefinitionBox: non esiste in Schema.org.

Allo stesso modo, non duplicare il corpo in JSON-LD semplicemente perché il box sembra importante. Il markup Schema deve descrivere la pagina in modo veritiero, e duplicare la prosa visibile in una proprietà non correlata crea rumore piuttosto che un significato più forte. Se una proprietà dello schema è popolata, il suo valore deve corrispondere alla definizione visibile nella sostanza e aggiornarsi con essa.

L’elemento non necessita di un ruolo ARIA interattivo. Renderizzalo nel normale ordine del documento come una regione etichettata o un contenitore semantico, con il titolo prima del corpo. Non usare role="alert", perché una definizione statica non è informazione urgente o appena arrivata. Non usare il colore o un’icona come unico segnale che il blocco è una definizione. Se il titolo è implementato come intestazione, il suo livello deve seguire la gerarchia della pagina; il ## nella fonte è una convenzione di mappatura dei campi, non un’istruzione per creare un salto di intestazione non valido.

Il comportamento da tastiera è il normale comportamento di lettura: il box stesso non è focalizzabile. Ogni link al suo interno segue la normale semantica dei link e necessita di un anchor descrittivo. L’output per screen reader deve preservare lo stesso ordine titolo-prima-del-corpo visibile sullo schermo.

Regole di scrittura

Scrivi la definizione prima di scrivere i suoi benefici. Inizia con il termine stesso, poi usa un verbo di collegamento come «è», «significa» o «si verifica quando». Indica la categoria utile più vicina e la caratteristica che separa il termine dai concetti vicini. Questa sequenza esiste perché la categoria senza distinzione è ampia, mentre la distinzione senza categoria lascia il lettore incerto su che tipo di cosa sia il termine.

Mantieni il corpo a un massimo di circa 300 caratteri, spazi inclusi. Preferisci una frase. Una seconda frase breve è accettabile solo quando un confine necessario non può essere espresso chiaramente nella prima. Il limite è editoriale, non un invito a comprimere la punteggiatura, rimuovere articoli o accumulare proposizioni. Se la precisione richiede più spazio, inserisci il nucleo esatto nel box e qualificalo immediatamente dopo.

Usa un tono neutro e dichiarativo. Evita «importante», «potente», «rivoluzionario», «devi sapere» e giudizi simili. Evita definizioni circolari come «l’ottimizzazione dei contenuti è l’atto di ottimizzare i contenuti». Espandi le abbreviazioni al primo utilizzo, a meno che l’abbreviazione stessa non sia il termine della pagina. Usa lo stesso nome canonico che appare nel titolo della pagina.

Non inserire mai questi elementi all’interno del corpo:

• Più di un termine primario o un elenco di termini correlati.
• Benefici, storia, cause, sintomi, esempi, passaggi, proposte di prodotto o inviti all’azione.
• Tabelle, immagini, video, moduli, pulsanti, note a piè di pagina o callout annidati.
• Superlativi non supportati, statistiche inventate o affermazioni che richiedono un paragrafo di prove.
• Una seconda intestazione, elenco puntato o citazione in blocco.
• Pronomi il cui significato dipende dall’introduzione precedente.

Un link di attribuzione è l’eccezione, non l’obiettivo. Usalo solo quando una definizione legale, scientifica o basata su standard dipende da una fonte nominata. Metti citazioni estese e disaccordi tra fonti nella prosa ordinaria, dove il lettore può vedere la qualificazione invece di scambiare una formulazione contestata per una definizione universale.

Tipi di post che lo utilizzano

Il frontmatter postTypes registra le associazioni definite. La tabella traduce queste associazioni in regole editoriali. I formati di tipo diagnostico/patologico e basati sui sintomi sono descritti qui come modelli d’uso, ma non sono collegati come tipi di post separati del playbook perché non sono nel registro canonico corrente.

Requisiti per tipo di post

Per le pagine di tipo diagnostico o patologico, usa il box sempre e posizionalo prima di sintomi, cause, gravità o rimedi. Per le pagine basate sui sintomi, usalo solo quando il nome del sintomo ha una definizione davvero breve e stabile. Se il box si limiterebbe a riformulare il titolo —«Un sito web lento è un sito web che è lento»— omettilo e inizia con la soglia diagnostica o il problema osservabile nella prosa.

Checklist QA

Un revisore verifica il significato prima dell’aspetto. Un box rifinito che contiene un’introduzione vaga è comunque una definizione fallita.

• Un termine principale: La pagina e il box definiscono esattamente un concetto primario.
• Posizione corretta: Il box è il primo blocco di contenuto creato dall’autore dopo l’introduzione, senza indice dei contenuti, punti chiave, galleria o promozione inseriti prima.
• Una sola occorrenza: Nessun secondo definition box compete con la risposta canonica.
• Definizione effettiva: Il corpo dichiara cos’è il termine o quando esiste la condizione; non si limita a dire perché il termine è importante.
• Formulazione autonoma: Il corpo nomina il suo soggetto e ha senso quando copiato senza la prosa o lo stile circostante.
• Precisione: Categoria, caratteristica distintiva e ogni confine essenziale sono accurati. La formulazione non generalizza eccessivamente.
• Lunghezza: Il corpo non supera circa 300 caratteri e rimane leggibile anziché compresso.
• Contenuti puliti: Nessun beneficio, storia, esempio, passaggio, affermazione di prodotto, media, tabella o elemento annidato appare all’interno.
• Decisione risposta diretta: Se la pagina chiede «Cos’è X?», il definition box è l’unico elemento di risposta diretta. Se entrambi gli elementi appaiono, rispondono a domande chiaramente diverse.
• Semantica accessibile: Il titolo precede il corpo, l’ordine delle intestazioni è valido, il colore non è l’unico identificatore e non sono presenti ruoli di avviso o target di focus non necessari.
• Parità portabile: Le mappature Markdown, Hugo e WordPress conservano lo stesso titolo e definizione.
• Moderazione dei dati strutturati: Ogni valore dello schema corrisponde al testo visibile e non viene utilizzato alcun tipo Schema.org inventato.
• Stato degli screenshot: I commenti rimangono istruzioni di acquisizione non renderizzate fino a quando i file nominati non esistono; nessun percorso immagine inesistente viene referenziato come immagine.

FAQ

Il template dell’academy renderizza le cinque domande esaminate memorizzate nel frontmatter [[faq]] di questa pagina. Insieme coprono la necessità, la coesistenza con le risposte dirette, i link e le citazioni, il limite di lunghezza e la regola di un box per pagina.