In qualità di collaboratore della Knowledge Base (la base di conoscenza di Mozilla), si utilizzano le parole per aiutare mezzo miliardo di utenti dei prodotti Mozilla. È un compito importante. Gli utenti accedono alla Knowledge Base da tutto il mondo e si aspettano soluzioni facili, ma si vuole anche sorprenderli con il nostro stile. Come si fa? Ecco alcuni suggerimenti emersi dalle nostre ricerche.

Tono

Scrivere tenendo presente il marchio. Mozilla si basa sulla scelta dell'utente. Crediamo nella libertà e nella flessibilità. Apprezziamo la privacy e la sicurezza. Siamo un'organizzazione non profit guidata dalla comunità con collaboratori in tutto il mondo che condividono valori comuni. Non è necessario ribadire questo concetto ogni volta che si scrive un articolo. È solo qualcosa da tenere a mente quando si descrivono le funzioni.

Stile di scrittura

Scrivere per un pubblico generico e non tecnico.

Vogliamo che i nostri articoli siano utilizzabili da tutti, non solo dagli utenti esperti. Ciò significa che scriviamo per un pubblico generico piuttosto che per un pubblico che ha molta familiarità con le tecniche e la terminologia informatica. Si deve partire dal presupposto che la persona per cui si sta scrivendo non sappia come modificare le preferenze o aggiungere un pulsante della barra degli strumenti senza istruzioni passo passo. Inoltre, si deve presumere che non abbia modificato nessuna delle impostazioni predefinite dell'applicazione o del sistema operativo.

In sintesi, è necessario seguire queste linee guida:

1. Essere brevi. Le persone accedono alla Knowledge Base in cerca di soluzioni rapide. Potrebbero non essere interessate al funzionamento interno dello strumento: vogliono solo sapere che cosa devono fare per risolvere il problema. Si può procedere sintetizzando. Vedere quanto si può comunicare con meno parole. È come la poesia!
2. Essere chiari. Evitare il gergo. Essere specifici. Utilizzare nel titolo e nell'articolo le parole che userebbe il lettore. Se il proprio nipote di 13 anni non lo capisce, scriverlo in modo che lo capisca. Per una guida più completa, consultare la sezione successiva.
3. Essere amichevoli, divertenti ed empatici (in breve: essere umani). Ok, gli utenti non si aspettano di divertirsi quando accedono al supporto. È questo che lo rende potente. Utilizzare un tono rilassato e un po' di umorismo per rendere la giornata dell'utente meno stressante. Prestare però attenzione a non sacrificare la chiarezza usando metafore o espressioni divertenti. Se non si è sicuri di come bilanciare questo aspetto, basta scrivere istruzioni semplici e utilizzare il tono scherzoso nell'introduzione o nella conclusione.
4. Raccontare una storia. Avere un inizio, una parte centrale e una fine. Ma non scrivere un romanzo (vedi linea guida n. 1).
   • Inizio: questo dà al lettore un po' di contesto. Di cosa tratta questo articolo e perché dovrebbe interessarmi? Essere brevi.
   • Parte centrale: le istruzioni vanno qui. Questa parte dovrebbe rispondere a "Come si fa?".
   • Fine: ci sono dei passaggi successivi all'articolo o alla funzione? Indicare al lettore che cosa dovrebbe consultare se vuole saperne di più. Leggere il paragrafo successivo per linee guida più complete.

Stile di scrittura (completo)

• Stile di scrittura colloquiale – Utilizzare uno stile informale e attivo, simile al modo in cui si parlerebbe con qualcuno di persona.
• Umorismo ed emozione – Usare l'umorismo è fantastico, ma a volte è difficile o impossibile da localizzare (tradurre in altre lingue). Emozioni come la sorpresa e "Non lo sapevo/Eureka!" potrebbero essere più facili da includere.
• Stili di apprendimento multipli – Proprio come a scuola, le persone imparano in modo diverso. Inoltre, tutti traggono vantaggio dal vedere lo stesso contenuto espresso in più modi.
• Ripetizione – Quando si spiega qualcosa in un modo diverso con mezzi diversi, ovviamente lo si sta anche ripetendo, il che è un altro buon modo per aiutare le persone a ricordare ciò che è importante.
• Immagini e video – L'uso di immagini e video insieme al testo non è solo la cosa migliore dopo l'aiuto di persona, è un modo semplice per includere più stili di apprendimento e ripetizione. Troppe immagini, tuttavia, possono rendere più difficile la localizzazione di un articolo, quindi provare ad aggiungere immagini solo quando è utile per un passaggio o un concetto. Ad esempio, per un passaggio che consiste nel fare clic su un pulsante, si potrebbe dire "Fare clic su OK" invece di aggiungere una schermata della finestra di dialogo di quel pulsante.
• Attività – Soprattutto in un tutorial, è bene dare alle persone qualcosa di utile da realizzare. Una cosa è leggere le istruzioni e capire il processo, ma spesso è utile ricordare e consentire alle persone di provare le cose.

Tipi di articolo

L'utilizzo di tipi di contenuto coerenti per gli articoli della Knowledge Base presenta molti vantaggi, tra cui la facilità di navigazione e una maggiore chiarezza e organizzazione, oltre ad aiutarci a creare contenuti in modo più efficace. Stiamo passando alla categorizzazione degli articoli esterni della Knowledge Base in quattro tipi, ciascuno con uno scopo specifico:

• Informativo (About): questi articoli rispondono a domande del tipo "Che cos'è…", fornendo informazioni essenziali per aiutare i lettori a comprendere un argomento.
• Procedura (How-to): questi articoli si concentrano sulla risposta a domande del tipo "Come fare a…?", guidando i lettori attraverso i passaggi necessari per raggiungere un obiettivo o una procedura specifici.
• Risoluzione di problemi (Troubleshooting): questi articoli aiutano gli utenti a identificare, diagnosticare e risolvere i problemi comuni che possono incontrare con un prodotto, servizio o funzione, rispondendo a domande del tipo "Come fare a…?" relative alla risoluzione dei problemi.
• Domande frequenti (FAQ): questi articoli contengono risposte concise a domande frequenti su un singolo argomento, che potrebbero non rientrare in altri singoli articoli della KB, fornendo un riferimento rapido per le domande comuni.

Iniziare con un titolo efficace e descrittivo

Un titolo ben realizzato è più di una semplice etichetta; è il primo punto di contatto di un utente con l'articolo della KB. Un buon titolo non dovrebbe solo attirare l'attenzione del lettore, ma anche fungere da anteprima concisa e informativa del contenuto dell'articolo. Quando si creano titoli per SUMO, considerare quanto segue:

• Chiarezza e descrittività: corrispondere a ciò di cui tratta l'articolo e a ciò che l'utente sta cercando. Essere concisi, ma incentrati sull'utente.
• Inclusione di parole chiave: incorporare parole chiave pertinenti per migliorare la visibilità sui motori di ricerca e aiutare gli utenti a trovare l'articolo.
• Concisione: mantenere i titoli brevi pur fornendo informazioni adeguate. I titoli più brevi sono spesso più facili da usare. Cercare di mantenere i titoli intorno ai 60 caratteri.
• Orientato all'azione: utilizzare verbi d'azione quando applicabile per indicare cosa possono fare gli utenti per risolvere un problema o raggiungere un obiettivo. Evitare di usare i gerundi (parole che terminano in "ing") nei titoli per garantire che rimangano orientati all'azione. Evitare di utilizzare titoli contenenti "Come fare a…".

Scrivere una buona introduzione

Insieme al titolo e all'indice, l'introduzione è ciò che aiuterà l'utente a determinare se si trova nel posto giusto.

• Per un articolo "Informativo": fornire una panoramica testuale o una definizione del concetto e concentrarsi sul motivo per cui l'utente dovrebbe interessarsene.
• Per un articolo "Procedura": fornire una panoramica testuale o una definizione dell'attività e concentrarsi sull'importanza o sui vantaggi dell'attività.
• Per un articolo "Risoluzione di problemi": descrivere il problema specifico o i sintomi che gli utenti possono incontrare. Scrivere in un linguaggio chiaro e conciso, evitando il più possibile il gergo tecnico.

Tenere presente che una buona introduzione può solitamente servire come un buon riassunto per la ricerca. Spesso è possibile semplicemente copiarla nel campo "Riassunto per i risultati della ricerca" e il gioco è fatto.

Organizzare l'articolo in modo efficace

L'idea generale è quella di cercare di sviluppare le competenze dal semplice al complesso, cercando di mantenere le informazioni necessarie alla maggior parte delle persone in cima. Quindi una soluzione semplice e comune di solito precede una soluzione complessa o per un caso limite.

Rendere le istruzioni passo passo facili da seguire

La cosa principale da tenere a mente quando si scrivono istruzioni passo passo è fare attenzione a includere tutte le azioni necessarie per completare l'attività. Se, ad esempio, è necessario fare clic su OK dopo aver selezionato una preferenza per passare al passaggio successivo, assicurarsi di includere il clic su "OK" come parte di quel passaggio. Alcune cose aggiuntive da considerare:

• Ci sono sempre più modi per ottenere un risultato. Si dovrebbe sempre scegliere il modo più intuitivo utilizzando l'interfaccia grafica utente e i menu quando possibile.
• Utilizzare frasi complete quando si descrive come accedere all'interfaccia utente.
• Includere i risultati attesi quando si danno istruzioni (ad esempio, Fare clic su "OK" e la finestra si chiuderà.).

Leggibilità

Il testo deve essere leggibile. Per fare ciò, è necessario:

• Suddividere un articolo in piccoli blocchi logici/semantici con sottotitoli.
• Utilizzare elenchi numerati o puntati.
• Scrivere frasi brevi o relativamente brevi.
• Evitare di scrivere paragrafi lunghi.

Non c'è limite alla quantità di testo. Più materiale c'è, meglio è; tuttavia, non si dovrebbe espanderlo artificialmente. Fornire solo informazioni utili, preziose e necessarie.

Come creare link alla documentazione esterna per software di terze parti

Quando si creano o si aggiornano articoli che comportano azioni all'interno di software di terze parti, come sistemi operativi o applicazioni esterne, è fondamentale fornire agli utenti informazioni accurate e affidabili. Tuttavia, includere i passaggi diretti per questo software nei nostri articoli può presentare delle sfide:

• Informazioni rapidamente obsolete: gli aggiornamenti del software di terze parti possono rendere le nostre istruzioni obsolete, confondendo o fuorviando potenzialmente i nostri utenti.
• Impegnativo in termini di risorse: il monitoraggio e l'aggiornamento continui dei passaggi per più piattaforme esterne richiederebbero sforzi e risorse significativi, che potrebbero non essere fattibili.

Procedure consigliate

Per garantire che i nostri utenti ricevano le informazioni più affidabili e aggiornate senza sovraccaricare le nostre risorse, seguire queste procedure consigliate:

• Link a risorse ufficiali: ogni volta che le istruzioni riguardano software di terze parti, trovare la documentazione ufficiale o gli articoli della guida forniti dal produttore del software. Inserire il link a queste risorse invece di scrivere i passaggi direttamente nei nostri articoli.
• Fornire un contesto: spiegare brevemente perché si sta indirizzando l'utente a una pagina esterna (ad esempio: "Per i passaggi più recenti e accurati per regolare le impostazioni di sistema, fare riferimento alla pagina di supporto ufficiale di <nome software>").
• Controllare periodicamente i link: sebbene miriamo a ridurre la manutenzione delle istruzioni di terze parti, è comunque importante controllare periodicamente che i link esterni siano ancora validi. Se si nota che un link è diventato obsoleto o non funzionante, cercare un link aggiornato alla documentazione ufficiale e inviare una revisione.
• Dichiarazione di non responsabilità sui contenuti esterni: quando si indirizzano gli utenti a un link esterno, chiarire che lasceranno SUMO e che non siamo responsabili del contenuto dei siti esterni. Una semplice dichiarazione di non responsabilità o una nota può essere sufficiente (ad esempio "Seguendo questo link si verrà reindirizzati a un sito web esterno non gestito da Mozilla.").

Esempio

Immaginare di scrivere un articolo sulla configurazione di una funzione di Firefox che si basa sulla modifica delle impostazioni a livello di sistema su un Mac. Invece di delineare i passaggi direttamente nell'articolo, si potrebbe scrivere:

Per i passaggi più recenti sulla regolazione delle preferenze di sistema su macOS, consultare la documentazione di supporto ufficiale di Apple visitando questa guida. Si noti che seguendo quel link si verrà indirizzati a un sito web esterno non gestito da Mozilla.

Ciò garantisce che si stiano seguendo le istruzioni più aggiornate direttamente dalla fonte.

Linee guida tecniche

• Per sapere come creare un nuovo articolo, leggere Creare un nuovo articolo della Knowledge Base.
• Per sapere come modificare un articolo esistente, leggere Modificare un articolo della Knowledge Base.
• Per una panoramica sul funzionamento della Knowledge Base, leggere Come funziona la Knowledge Base.
• Per un elenco completo della documentazione relativa agli articoli, leggere Migliorare la Knowledge Base.

Titolo

• Lunghezza del titolo: la pagina dei risultati di ricerca di Google visualizzerà fino a 60 caratteri. Il titolo può essere più lungo se necessario, ma assicurarsi che le parole chiave importanti siano incluse nei primi 60 caratteri.
• Maiuscole: la prima parola del titolo deve essere maiuscola, così come i nomi propri e i nomi di marchi, non ogni parola principale. Utilizzare lo stile "frase", non lo stile "titolo". (Lo stesso vale per i titoli delle intestazioni. Per altre regole sull'uso delle maiuscole, consultare la sezione Guida di stile e regole di redazione più avanti). Non modificare, tuttavia, il titolo di un articolo esistente per cambiare le maiuscole a meno che non si apportino altre modifiche al titolo, poiché non verrà creato un reindirizzamento e ciò comporterà la rottura dei link wiki negli articoli che rimandano a esso (bug 1969540).
• Non utilizzare i due punti nel titolo dell'articolo poiché impediscono la creazione di un link wiki a quell'articolo (bug 749835). Assicurarsi inoltre di non avere spazi extra nel titolo dell'articolo, che impedirebbero anche il funzionamento dei link wiki.
• Provare a variare il modo in cui si nominano gli articoli. Non utilizzare le stesse parole o frasi in ogni titolo. Ad esempio, non iniziare sempre gli articoli con "Come" ed evitare di utilizzare nomi di attività che terminano in "ing" come "Impostazione della pagina iniziale".
• Ricordare che l'intera spiegazione non deve essere inserita nel titolo. È possibile utilizzare il riassunto per fornire all'utente informazioni aggiuntive su ciò che è contenuto nell'articolo.

Slug

Quando si crea un nuovo articolo e si inserisce un titolo, SUMO creerà automaticamente uno slug (la parte dopo kb/ alla fine dell'URL dell'articolo). Un revisore può modificare il titolo di un articolo esistente ma lo slug rimane lo stesso, a meno che non venga modificato manualmente (questo è intenzionale). Lo slug ha un limite di 50 caratteri. Gli spazi vengono resi come trattini. Lo slug dovrebbe essere coerente con il titolo, ma dato il vincolo di spazio più stretto, non è necessario che sia lo stesso.

Correggere lo slug

Assicurarsi di controllare la fine dello slug generato automaticamente. A volte una parola viene tagliata o finisce con un trattino. Si prega di correggere cose del genere.

Aggiornare lo slug da un articolo esistente

Quando si aggiorna il titolo di un articolo esistente, mantenere lo slug corrente invariato a meno che il nuovo titolo non rappresenti un cambiamento significativo che non si allinea più con lo slug esistente. Mantenere lo slug coerente aiuta a evitare link non funzionanti e preserva il valore SEO.

Categorie, prodotti e argomenti

Per la maggior parte, un articolo appartiene alla categoria Procedura o Risoluzione di problemi. Occasionalmente, scriviamo articoli in una delle altre categorie, come gli articoli "Come contribuire" (come questo). La pagina della cronologia dell'articolo mostrerà la categoria.

Gli articoli sono anche "rilevanti per" almeno un prodotto. Appartengono anche a un "Argomento" principale e, facoltativamente, a un "sotto-argomento".

Parole chiave

Il campo delle parole chiave in un articolo può essere utilizzato per migliorare i risultati di ricerca su SUMO. Dovrebbe essere utilizzato solo in circostanze specifiche, poiché un uso improprio può effettivamente danneggiare la ricerca. Raramente è necessario utilizzare le parole chiave. Per i dettagli, leggere Quando e come utilizzare le parole chiave.

Scrivere un buon riassunto per la ricerca

Il riassunto dell'articolo, insieme al titolo, aiuta gli utenti a giudicare se un articolo risponderà alla loro domanda. Chiamiamo questo "Fiducia dell'utente" e influisce direttamente sulle percentuali di clic. Anche se forniamo l'articolo corretto in cima all'elenco dei risultati di ricerca, l'utente deve stabilire la connessione mentale tra la query di ricerca e i risultati che visualizziamo affinché faccia clic per accedere all'articolo.

Un riassunto per un articolo di procedura dovrebbe includere gli argomenti trattati nell'articolo. Un articolo sulla risoluzione dei problemi dovrebbe cercare di includere i sintomi. Inoltre, un riassunto dovrebbe seguire queste linee guida:

• Breve e diretto. Ricordate gli annunci economici? Scriverlo in quel modo. I motori di ricerca possono tagliare qualsiasi cosa più lunga di 140 caratteri. Se si utilizza un riassunto più lungo, mantenere le informazioni importanti all'inizio. Nota: il software della KB mostrerà 20 caratteri rimanenti quando il riassunto raggiunge i 140 caratteri perché il limite di ricerca interno è 160.
• Non utilizzare la sintassi wiki.
• Non utilizzare "Questo articolo spiega" in ogni riassunto. Variarlo quando possibile. Alcune altre frasi da considerare:
  • Vi mostreremo
  • Spiegheremo
  • Questa pagina spiega
  • Questo articolo descrive
  • Scopri come

Numero di passaggi

Quando si guidano gli utenti attraverso un processo, considerare gli elenchi ordinati (elenchi numerati). È generalmente una buona pratica cercare di mantenere il numero totale di passaggi nell'intervallo di sei-sette.

Struttura parallela

Utilizzare la stessa formulazione o modello di parole per ogni passaggio che si scrive. La struttura parallela è importante negli articoli della KB perché rende le cose chiare e facili da seguire. Quando elementi simili hanno un formato coerente, gli utenti possono comprendere e completare le attività più agevolmente. Questa struttura semplifica le istruzioni, riduce gli errori e garantisce che le informazioni vengano trasmesse in modo efficace.

Ad esempio:

1. Individuare Cancella la cronologia alla chiusura di Firefox. Se è selezionato:
   1. Fare clic sul pulsante Impostazioni….
   2. Assicurarsi che Cronologia moduli e ricerche non sia selezionato.
   3. Fare clic su OK.

Indicazioni direzionali

Le indicazioni direzionali sono riferimenti o indicatori che guidano gli utenti verso la posizione o la posizione specifica all'interno di un'interfaccia utente in cui devono intraprendere un'azione particolare. Queste indicazioni aiutano gli utenti a navigare e interagire con software, applicazioni o siti web in modo più efficace. In genere includono frasi come "Nell'angolo in alto a destra", "Nel menu a sinistra" o "Sotto la barra di ricerca", che forniscono agli utenti un'idea chiara di dove trovare ed eseguire le azioni.

Nelle istruzioni dell'articolo della KB, assicurarsi di fornire indicazioni direzionali prima dell'azione. Ad esempio, invece di dire Fare clic sul pulsante, utilizzare Nell'angolo in alto a destra, fare clic sul pulsante. Questo formato aiuta gli utenti a individuare ed eseguire facilmente le azioni all'interno dell'interfaccia.

Guida di stile e regole di redazione

Come detto prima, quando si scrive si dovrebbe usare uno stile attivo e colloquiale. Evitare di dire cose come "Se i segnalibri di un utente sono andati persi" e dire invece "Se hai perso i tuoi segnalibri". Ecco altri problemi comuni di stile e di redazione che si possono incontrare quando si scrivono articoli di supporto: Utilizzare sempre i termini così come appaiono nell'interfaccia di Mozilla. Ad esempio:

• Plugin non ha il trattino.
• Componenti aggiuntivi (Add-on) ha il trattino.
• Pagina iniziale (Home page) è composto da due parole.

Termini informatici generali:

• Sito web è una parola. Pagina web sono due parole.
• Le forme verbali sono "accedere" e "disconnettersi" (o "uscire"). Esempio: "Accedere al sito web". Lo stesso vale per "sign in" e "sign out".
• Le forme sostantivate sono "accesso" e "disconnessione" (o "logout"). Esempio: "Fare clic sul pulsante di accesso."
• Utilizzare email invece di e-mail.
• Il plurale di CD-ROM è CD-ROM.

I link a mozilla.org e firefox.com non devono contenere la locale:

• Utilizzare https://www.mozilla.org/ invece di https://www.mozilla.org/en-US/
• Utilizzare https://www.firefox.com/ invece di https://www.firefox.com/en-US/

Quando si incorporano link nelle frasi:

• Evitare di usare "fai clic qui" o "qui" come testo del link.
  • Sì: vai alle impostazioni del tuo account per annullare l'abbonamento.
  • No: fai clic qui per annullare l'abbonamento.

Utilizzare la maiuscola per i seguenti elementi:

• Nomi propri e nomi, inclusi nomi di marchi, nomi di prodotti e nomi di funzioni
• La prima parola di una frase completa
• Le lettere di abbreviazioni e acronimi, a meno che non siano normalmente minuscole
• La prima parola negli elenchi numerati o puntati
• Il nome di un tasto sulla tastiera
• La prima parola di una frase completa dopo i due punti
• La prima parola in un'intestazione o in un titolo

Mozilla accounts:

• La "a" in Mozilla accounts è sempre minuscola tranne che negli elementi di navigazione in cui è inclusa con altri elementi di navigazione che utilizzano le maiuscole per i titoli.
• Utilizzare sempre "sign in" e "sign out".
• Nella forma verbale, utilizzare "sign in to your account" (non "sign into") per essere grammaticalmente corretti.
• È anche possibile utilizzare "Sign in with Mozilla".
• "Sign" dovrebbe essere sempre usato come verbo. Se lo si usa come sostantivo, usare "login".
• Utilizzare "sign up" come invito all'azione per creare un nuovo account.

Per i dettagli su come fare riferimento a Mozilla accounts negli articoli della KB, leggere Editorial guidelines for Mozilla accounts.

Non usare "i.e." e "e.g.". Queste abbreviazioni latine possono confondere le persone. Per motivi di chiarezza, utilizzare "in altre parole" o "per dirla diversamente" invece di i.e. quando si vuole spiegare qualcosa in un modo diverso. Utilizzare "per esempio", "ad esempio" o "come" invece di e.g. quando si vogliono fornire esempi.

Non usare le virgole seriali in un elenco di elementi. Ad esempio, usare "Estensioni, temi e plugin" (senza la virgola seriale), non "Estensioni, temi, e plugin".

Utilizzare inizialismi che sono considerati generalmente compresi. Ad esempio:

• HTTP
• USB
• URL

I numeri che compaiono nella versione di un prodotto, nei codici di errore, nei tasti e nei pulsanti non saranno scritti per esteso.

Scrivere le istruzioni in forma attiva. Scrivere le istruzioni in forma attiva. La forma attiva e il tempo presente semplificano le istruzioni, rendendole più facili da seguire e incoraggiando un'azione tempestiva. Esempio:

"Riavviare Firefox per aggiornare" non "Firefox deve essere riavviato".

Scrivere per esteso le barre rovesciate (\) e le barre (/) per percorsi e ricerche per evitare confusione.

Esempio: "Alcuni percorsi di immagini contengono barre rovesciate (\\)".

Scorciatoie da tastiera Utilizzare la maiuscola per la prima lettera di una scorciatoia da tastiera o di una combinazione di scorciatoie: Ctrl + Shift + C o Command + Shift + C.

Non usare slang e modi di dire. Tutti i nostri articoli sono tradotti in molte lingue diverse, quindi vengono letti e tradotti da persone non di madrelingua inglese. Lo slang e i modi di dire possono essere ambigui, il che può confondere i lettori e rendere più difficile la traduzione.

Disponiamo di stili visivi speciali per una serie di elementi che possono essere ottenuti aggiungendo la sintassi wiki appropriata attorno all'elemento. Per gli stili più comuni, consultare l'articolo Marcatori più utilizzati della sintassi Wiki.

Disponiamo di una sintassi wiki speciale – {for} – che consente di indirizzare le informazioni a versioni specifiche di Firefox o a sistemi operativi specifici. Ad esempio, è possibile visualizzare una serie di istruzioni per le persone che utilizzano Windows e un'altra per le persone che utilizzano macOS (per i dettagli, leggere Come utilizzare l'istruzione For).