Regole del Buono e del Cattivo: Linee Guida Accoppiate

Un blocco buono e cattivo abbina un’azione consigliata a un errore dello stesso ambito e spiega perché l’errore fallisce. Il suo valore deriva dal contrasto: la versione errata espone una modalità di fallimento allettante, mentre la versione corretta fornisce al lettore un sostituto immediato.

Questo esempio renderizzato è il modello di produzione. Ogni riga affronta un argomento con lo stesso livello di dettaglio. Il “Cattivo” nomina un errore realistico e la sua conseguenza; il “Buono” fornisce una correzione utilizzabile. Le etichette, non il colore o le icone, portano la distinzione.

Perché questo elemento è importante

Le regole sono più facili da comprendere quando i lettori possono vedere il confine che devono rispettare. Un’istruzione positiva da sola può sembrare astratta: “Usa prove specifiche” non rivela cosa sia considerato troppo vago. Un’istruzione negativa da sola crea attrito: “Non fare affermazioni infondate” dice cosa evitare ma lascia poco chiaro il passo successivo. Metterle insieme trasforma un confine in una scelta su cui il lettore può agire.

La versione sbagliata è istruttiva perché spesso somiglia a ciò che una persona indaffarata scriverebbe naturalmente. Mostrare quell’errore ravvicinato aiuta il lettore a riconoscerlo nel proprio lavoro. La motivazione conta altrettanto. “Non usare un linguaggio vago” richiede obbedienza; “Non scrivere ‘veloce’ senza nominare l’attività misurata, perché i lettori non possono verificarla o confrontarla” insegna un principio che si trasferisce a nuovi esempi.

La parità significa che entrambi i lati coprono soggetti equivalenti, conteggi, dettagli e peso editoriale. Impedisce a una colonna “Buono” rifinita di sedere accanto a un cumulo di avvertimenti non correlati. I lettori possono scansionare una coppia, comprendere il contrasto e proseguire senza dover ricordare un elemento proveniente da un’altra parte della pagina.

L’estraibilità automatica è la capacità del software di isolare i contenuti preservandone il significato e le relazioni. Intestazioni visibili, struttura a elenco e coppie allineate per riga permettono ai sistemi di ricerca e ai motori di risposta di recuperare affermazioni come “Per i prezzi, indica il piano e la data; evita cifre senza data perché il loro ambito non è verificabile.” Se i due lati contengono punti elenco non correlati o la motivazione è implicita solo tramite un’icona, l’estrazione può preservare il comando perdendo la qualifica che lo rende sicuro.

Segui le regole di scrittura degli elementi prima di selezionare questo blocco. Lo scopo ha la precedenza sull’aspetto. I contenuti che avvertono principalmente di un pericolo immediato rimangono un avvertimento; una sequenza rimane un elenco di passaggi; un insieme finito di controlli di completamento rimane una checklist. Due colonne colorate non trasformano quegli scopi in buono e cattivo.

Quando usarlo

Usa questo elemento quando i lettori hanno bisogno di distinguere una pratica consigliata da un errore plausibile e conseguente. Il contrasto dovrebbe ridurre l’ambiguità in modo più efficace di una singola istruzione. Gli argomenti adatti includono standard editoriali, convenzioni di implementazione, controlli di qualità, comportamento di design, gestione dei dati e scelte procedurali.

Tutte queste condizioni dovrebbero essere vere:

1. Ogni errore ha un’azione sostitutiva responsabile.
2. Il motivo per evitare l’errore può essere enunciato in una breve frase.
3. Gli elementi sono linee guida indipendenti, non passaggi che devono essere completati in ordine.
4. Entrambi i lati possono usare lo stesso ambito e livello di specificità.

I casi di errore ravvicinato sono comuni:

• Pro e contro: vantaggi e limiti valutano un’unica opzione. Il buono e cattivo istruisce il comportamento del lettore. “Include progetti illimitati” è un pro, non un buono.
• Avvertimento: una conseguenza grave o irreversibile necessita di evidenza diretta e di una risposta, non di una colonna compagna di pari peso.
• Checklist: una checklist verifica se il lavoro richiesto è completato. Il suo stato non spuntato non è un “Cattivo.”
• Tabella comparativa: una tabella valuta diverse opzioni secondo criteri condivisi. Non prescrive comportamenti corretti e scorretti.
• Prima e dopo: due esempi possono mostrare una modifica senza esprimere una regola comportamentale riutilizzabile. Usa il buono e cattivo solo quando il contrasto insegna una pratica generale.
• Stile redazionale arbitrario: se non è possibile spiegare alcuna conseguenza per il lettore, il sistema, la conformità o la manutenzione, documenta la convenzione come regola invece di fingere che l’alternativa sia un errore.

Non usare il blocco per creare opposizione artificiosa. “Scrivi chiaramente; non scrivere in modo poco chiaro” ribadisce la stessa astrazione e non insegna nulla. Il lato sbagliato deve essere abbastanza allettante da essere riconoscibile e abbastanza specifico da essere diagnosticato.

Dove posizionarlo

Posiziona il blocco dopo che la pagina ha definito l’attività, il pubblico e gli eventuali termini necessari per comprendere le linee guida. Si trova immediatamente dopo la spiegazione o dimostrazione che riassume, o verso la fine di una sezione come ripasso pratico prima che il lettore agisca.

Regole di posizionamento esatte:

• Introduci un argomento nell’intestazione più vicina. Ogni coppia deve avere senso sotto quell’argomento senza prendere in prestito l’ambito da un paragrafo distante.
• Metti il blocco dopo il principio guida e prima di una checklist di implementazione o dell’azione successiva. I lettori dovrebbero capire il perché prima di verificare il completamento.
• In sezioni ripetute, usa la stessa posizione e gli stessi limiti di coppia. Spostare il blocco in modo imprevedibile rende più difficile la scansione tra gli argomenti.
• Tieni gli elenchi accoppiati insieme nell’ordine del sorgente e nella disposizione visiva. La prosa esplicativa può seguire il blocco completo, non dividerne i lati.

Non può trovarsi direttamente accanto a un altro elemento decisionale a due colonne, perché griglie adiacenti oscurano quali etichette e righe appartengono insieme. Non posizionare una testimonianza, un banner promozionale, un modulo o un invito all’azione tra i lati “Buono” e “Cattivo.” Non renderlo il primo contenuto significativo di una pagina quando le regole dipendono da termini o contesto che il lettore non ha ancora ricevuto.

Anatomia

Legenda renderizzata

1. Intestazione dell’argomento: nomina l’attività o decisione delimitata condivisa da ogni coppia.
2. Etichetta Buono: testo visibile che identifica il comportamento consigliato; un’icona o un trattamento verde è supplementare.
3. Etichetta Cattivo: testo visibile che identifica il comportamento da evitare; la punteggiatura usa la forma editoriale localizzata.
4. Dichiarazione d’azione: un’istruzione imperativa o dichiarativa che nomina un comportamento osservabile.
5. Motivazione: una frase che collega l’istruzione a una conseguenza, modalità di fallimento o principio guida.
6. Relazione di coppia: l’ordine nel sorgente e la disposizione preservano quale “Buono” corrisponde a quale “Cattivo.”
7. Nota sulla fonte opzionale: identifica la policy, il test, il regolamento o la prova che governa i requisiti fattuali.

L’autore fornisce l’argomento, le coppie e le motivazioni. Il renderer fornisce presentazione equa, impilamento reattivo, etichette accessibili e icone decorative dove appropriato.

Esempi di design

Le seguenti varianti sono l’insieme supportato completo. Cambiano densità e disposizione, mai il contratto di parità o motivazione.

Righe accoppiate standard

Usa da tre a sette righe allineate orizzontalmente su schermi larghi. Ogni riga contiene un “Buono” e un “Cattivo” sullo stesso argomento.

Coppie impilate per mobile

A larghezze ridotte, mantieni ogni coppia insieme: “Buono,” poi “Cattivo,” poi la coppia successiva. Impilare tutti gli elementi positivi prima di tutti quelli negativi nasconderebbe la corrispondenza.

Variante guidata da esempi

Usala quando il linguaggio esatto, il markup o il comportamento dell’interfaccia sono più utili di un comando astratto. Ogni lato mostra un breve esempio seguito dalla sua motivazione. Il codice rimane testo selezionabile.

Variante compatta di ripasso

Usala solo quando le motivazioni guida sono già state spiegate immediatamente sopra. La motivazione appare comunque in ogni elemento, ma in una breve frase anziché in un paragrafo separato.

Non creare varianti con sole icone, caroselli, schede o elementi collassabili indipendentemente. Separano la coppia, nascondono un lato o rendono il confronto dipendente dall’interazione.

Parametri

Il contratto modella coppie piuttosto che due elenchi non correlati. “Fonte” descrive dove il renderer ottiene ogni valore.

La prima intestazione del corpo corrisponde a heading. Ogni pair annidata possiede entrambe le azioni ed entrambe le motivazioni. Il modello della fonte non deve memorizzare tutti gli elementi positivi separatamente da tutti quelli negativi, perché ciò renderebbe la corrispondenza delle righe dipendente dalla posizione nell’array e facile da rompere durante la modifica.

Sintassi ed esempi di codice

Tutti e tre i formati preservano lo stesso argomento, ordine delle coppie, azioni e motivazioni. Non deducono una motivazione dall’azione né creano automaticamente un elemento positivo.

Direttiva Markdown portabile

:::dos-and-donts
## Writing comparison claims

::item{do="Name the exact plan and date checked" dont="Do not publish an undated price"}
### Do
Commercial facts change, so scope lets readers verify and reuse the claim.

### Don't
Readers cannot tell which plan or period an undated figure describes.
::

::item{do="Compare both products on the same criterion" dont="Do not compare unrelated capabilities"}
### Do
A shared measure makes the difference meaningful.

### Don't
Different criteria create the appearance of comparison without a valid choice.
::
:::

Questo elemento sovrascrive il mapping predefinito degli elementi: l’intestazione padre fornisce heading; gli attributi dell’elemento forniscono le azioni; le prime sottotestate Do e Don't mappano il loro testo successivo alle due motivazioni.

Shortcode Hugo

Nessuno shortcode Hugo di produzione implementa attualmente il contratto di record accoppiati. Finché non esiste, renderizza HTML semantico come nell’esempio dal vivo invece di usare due helper di elenco non correlati. L’adattatore previsto è:

{{< dos-and-donts >}}
## Writing comparison claims

{{< do-dont-pair do="Name the exact plan and date checked" dont="Do not publish an undated price" >}}
### Do
Commercial facts change, so scope lets readers verify and reuse the claim.
### Don't
Readers cannot tell which plan or period an undated figure describes.
{{< /do-dont-pair >}}
{{< /dos-and-donts >}}

Il renderer futuro deve produrre una regione etichettata con un elenco di record accoppiati. Non deve creare due array e abbinarli per indice dopo il rendering.

Blocco o shortcode WordPress

[dos_and_donts heading="Writing comparison claims" variant="standard"]
[pair]
[do action="Name the exact plan and date checked"]Commercial facts change, so scope lets readers verify and reuse the claim.[/do]
[dont action="Do not publish an undated price"]Readers cannot tell which plan or period an undated figure describes.[/dont]
[/pair]
[pair]
[do action="Compare both products on the same criterion"]A shared measure makes the difference meaningful.[/do]
[dont action="Do not compare unrelated capabilities"]Different criteria create the appearance of comparison without a valid choice.[/dont]
[/pair]
[/dos_and_donts]

Un blocco WordPress personalizzato dovrebbe modificare ogni coppia come un singolo record e impedire la pubblicazione quando manca un’azione o una motivazione.

Esempi

Buono: equivalente, attuabile e motivato

Le coppie condividono un soggetto in ogni riga: ambito del piano, finestra temporale e stato delle prove. Entrambe le azioni sono abbastanza specifiche da essere verificate in una bozza, e ogni motivazione spiega cosa può andare storto. Un lettore può applicare il principio anche quando il prezzo, il prodotto o il periodo esatti cambiano.

Cattivo: due cumuli di comandi

Questo fallisce perché le colonne non sono correlate e non sono bilanciate. “Sii accurato” non ha una condizione di completamento osservabile, mentre “Non usare mai il gergo” proibisce un linguaggio senza distinguere i termini necessari da quelli non spiegati. Nessuno degli elementi negativi enuncia una conseguenza, e la cella vuota rivela che l’autore ha creato due elenchi invece di quattro coppie.

Ripara il blocco scegliendo un argomento, poi scrivendo righe equivalenti. Per la terminologia, la coppia potrebbe essere: “Definisci un termine specialistico necessario al primo utilizzo, perché la definizione permette ai nuovi arrivati di seguire il ragionamento” e “Non sostituire un termine preciso con una frase vaga di uso quotidiano, perché la sostituzione può alterare il significato.” La correzione insegna un giudizio invece di imporre uno slogan.

Markup schema e accessibilità

Schema.org non fornisce un tipo generale DoAndDont. Mantieni il blocco visibile all’interno dell’Article, TechArticle, HowTo o altri dati strutturati a livello di pagina quando quella pagina si qualifica genuinamente. Non convertire gli elementi positivi in record HowToStep a meno che non formino una procedura ordinata, e non pubblicare le coppie come FAQPage solo perché contengono brevi spiegazioni.

Usa intestazioni ed elenchi nativi. Una sezione esterna riceve il suo nome accessibile dall’intestazione dell’argomento. Ogni coppia dovrebbe essere un elemento di elenco o un record raggruppato contenente un’etichetta “Buono” visibile e un’etichetta “Cattivo” visibile. Preserva ogni coppia nell’ordine del sorgente in modo che un utente di screen reader incontri la raccomandazione e il suo errore corrispondente insieme.

Colore e icone sono supplementari. Il verde non può essere l’unico segnale per “Buono,” e una croce non può essere l’unico segnale per “Cattivo.” Le icone decorative ricevono testo alternativo vuoto o sono nascoste alla tecnologia assistiva. Non rendere un blocco statico focalizzabile. Se il traboccamento orizzontale è inevitabile per una tabella di esempio, contieni ed etichetta la regione di scorrimento; il componente di produzione dovrebbe invece impilare le coppie.

La contrazione “Don’t” è accettabile come copia editoriale visibile. I campi di codice usano dont compatibile ASCII dove gli apostrofi complicherebbero i nomi degli attributi. I renderer localizzano le etichette senza modificare le azioni o le motivazioni memorizzate.

Regole di scrittura

Scrivi la motivazione prima di finalizzare il comando. Questo obbliga l’autore a identificare la conseguenza per il lettore, il sistema, la sicurezza, la conformità o la manutenzione. Se non è possibile scrivere una motivazione difendibile, il divieto potrebbe essere una preferenza piuttosto che una linea guida.

Usa da tre a sette coppie. Ogni azione dovrebbe esprimere un comportamento osservabile in 110 caratteri o meno, dove pratico. Dai a ogni lato una frase di motivazione di non più di 180 caratteri. I limiti mantengono i due lati scansionabili; qualifiche più lunghe appartengono alla prosa circostante.

Mantieni la parità in cinque dimensioni:

• Soggetto: entrambe le azioni affrontano la stessa decisione o artefatto.
• Altitudine: una regola di markup precisa non può essere accoppiata con una massima ampia come “scrivi bene.”
• Grammatica: usa imperativi paralleli o dichiarazioni parallele.
• Prove: applica la stessa soglia fattuale e di citazione a entrambi i lati.
• Peso visivo: nessun lato riceve più spazio, enfasi, dettaglio o visibilità predefinita.

Usa un linguaggio diretto e neutro. Preferisci “Non pubblicare un prezzo non verificato” a un linguaggio umiliante come “Solo gli scrittori negligenti dimenticano di verificare i prezzi.” Evita sarcasmo, paura e termini assoluti a meno che la regola non sia genuinamente assoluta e il suo ambito sia dichiarato.

Non inserire mai questi elementi all’interno del blocco:

• Suggerimenti non correlati aggiunti per riempire un lato o forzare la simmetria numerica.
• Un divieto senza una conseguenza, un principio o un’azione sostitutiva.
• Procedure ordinate, caselle di spunta, valutazioni, verdetti o vantaggi e limiti del prodotto.
• Avvertenze critiche per la sicurezza, esclusioni di responsabilità legali, istruzioni di emergenza o avvisi di azione irreversibile.
• Testimonianze, citazioni lunghe, contenuti multimediali, moduli, inviti all’azione, pulsanti promozionali o codici sconto.
• Accordion annidati, schede, caroselli, tabelle comparative o un altro blocco buono e cattivo.
• Affermazioni su persone o gruppi inquadrate come fallimento morale piuttosto che comportamento osservabile.

Quando un requisito proviene da una policy, un regolamento, un test o uno standard esterno, aggiungi una nota sulla fonte nelle vicinanze. Attribuisci la regola con sufficiente precisione affinché un editor possa ricontrollarla; non far sì che il blocco trasporti un lungo apparato di citazioni.

Tipi di articolo che lo utilizzano

L’array postTypes nel frontmatter guida questa matrice di utilizzo. L’inclusione rende l’elemento disponibile alla condizione indicata; non rende il blocco obbligatorio su ogni pagina di quel tipo.

Checklist QA

• Il blocco ha un argomento delimitato chiaro dalla sua intestazione più vicina.
• Il principio guida appare prima del blocco, così le coppie rafforzano piuttosto che inventare la regola.
• Ci sono da tre a sette coppie complete e esattamente lo stesso numero di azioni “Buono” e “Cattivo.”
• Ogni coppia affronta lo stesso soggetto, pubblico, ambito e livello di specificità.
• Ogni “Cattivo” nomina un errore realistico e spiega la sua conseguenza o modalità di fallimento.
• Ogni “Buono” fornisce un sostituto attuabile e spiega perché funziona.
• Nessun elemento semplicemente nega il suo compagno, ripete uno slogan o usa una formulazione circolare.
• Le azioni contengono un comportamento e si mantengono vicine al target di 110 caratteri.
• Le motivazioni contengono una frase e rimangono entro 180 caratteri.
• Entrambi i lati usano grammatica parallela, standard probatori, dettaglio e peso visivo.
• I requisiti fattuali identificano la loro policy, regolamento, test o fonte dove necessario.
• Il blocco non contiene passaggi, stati di spunta, compromessi di prodotto, avvertenze gravi, promozioni, moduli o elementi complessi annidati.
• Il testo visibile dice “Buono” e “Cattivo”; colore, posizione e icone non sono gli unici segnali.
• L’output reattivo mantiene ogni coppia insieme invece di impilare tutti gli elementi positivi prima di tutti quelli negativi.
• L’intestazione dell’argomento e la struttura delle coppie rimangono comprensibili in testo semplice e quando stili o script non sono disponibili.
• I dati strutturati descrivono solo la pagina contenitore e non inventano un tipo schema buono-e-cattivo.
• I commenti degli screenshot rimangono istruzioni di acquisizione non renderizzate fino all’esistenza di risorse reali.

FAQ

Il modello academy renderizza le cinque domande memorizzate nei [[faq]] del frontmatter di questa pagina. Coprono completezza delle coppie, parità numerica, motivazioni, dati strutturati e conteggio degli elementi.