La documentazione di Discourse è attualmente in fase di revisione e modifica per allinearsi a questa guida di stile. Non tutti gli argomenti della documentazione corrispondono attualmente a questo standard: stiamo lavorando il più rapidamente possibile per raggiungerlo.
Questo è considerato un documento vivente che guida la scrittura e la formattazione della documentazione di Discourse. Questo argomento verrà aggiornato secondo necessità. Se hai dubbi su uno dei principi qui riportati, pubblica un messaggio nell’argomento per discutere i dettagli.
Il principio guida di questa guida di stile per la documentazione è considerare i lettori e le loro esigenze durante la scrittura: cosa vogliono ottenere? Qual è il tuo obiettivo nel fornire questo contenuto?
Checklist rapida per l’implementazione della guida di stile:
- Il blocco Meta è presente e corretto
- Il titolo è orientato all’azione
- Tutti i titoli utilizzano la maiuscola solo per la prima lettera della frase (sentence case)
- Vengono utilizzati tag e categorie corretti
- Il documento è strutturato logicamente
Al termine della stesura di un documento, rivedilo per assicurarti che tutti questi criteri siano soddisfatti.
Si prega di prendere nota di queste linee guida per la formattazione del testo:
Informazioni Meta
- Il documento deve appartenere a una e una sola delle seguenti categorie:
- Utilizzo di Discourse
- Guide generali per utenti per attività non amministrative
- Gestione del sito
- Impostazioni, plugin, contenuti e amministrazione generale del sito
- Integrazioni
- Guide per l’integrazione di altre piattaforme con Discourse
- Clienti Hosted
- Guide rilevanti solo per i clienti hosted
- Self-hosting
- Guide rilevanti solo per siti self-hosted
- Guide per Sviluppatori
- Guide tecniche per lo sviluppo su Discourse, inclusa la creazione di temi, componenti dei temi e plugin
- Contributi
- Guide per contribuire al progetto open-source di Discourse
- Utilizzo di Discourse
- Il documento deve appartenere a una e una sola delle seguenti tag / tipi di documento:
#how-to#explanation#reference#tutorial
- Il documento può avere qualsiasi altro tag applicabile, con un massimo assoluto di 5 tag su un singolo documento
Blocco Meta
Tutti i documenti devono avere un blocco in alto che includa una breve spiegazione di cosa tratta il documento, nonché eventuali informazioni meta aggiuntive rilevanti, come i requisiti sul livello utente, se è richiesto l’accesso alla console o qualsiasi altra cosa. Questo sarà formattato come un blocco di citazione senza un titolo sopra. Ecco un esempio di come deve apparire:
Questa è una guida per descrivere tutte le impostazioni nascoste del sito disponibili, come abilitarle e perché potresti volerle modificare.
Livello utente richiesto: Amministratore
Accesso alla console richiesto
Titoli e Intestazioni
- Rendi i titoli dei documenti orientati all’azione
- Errato: “Come abilitare i titoli automatici per i thread della chat”
- Corretto: “Abilitazione dei titoli automatici per i thread della chat”
- I titoli dei documenti non devono essere troppo lunghi
- Per gli argomenti ‘how-to’, rendi il titolo orientato all’obiettivo
- Tutti i titoli devono essere specifici e unici
- Non utilizzare punteggiatura o caratteri speciali nei titoli dei documenti, tranne le virgole
- Non includere emoji nei titoli dei documenti
- Utilizza la maiuscola solo per la prima lettera della frase (sentence case) per titoli e intestazioni: ciò significa che solo la prima parola inizia con la maiuscola, insieme ai nomi propri e a qualsiasi altra parola che normalmente sarebbe maiuscola
- Non utilizzare il simbolo della e commerciale (&) nelle intestazioni; usa invece la parola completa (“e”)
Linee guida generali per la scrittura, tono e grammatica
- Usa la voce in seconda persona link quando ti riferisci alle persone che leggono il documento: usa “tu”, non “noi”
- Usa la voce attiva il più possibile
- Errato: “il pulsante deve essere cliccato”
- Corretto: “clicca il pulsante”
- Definisci acronimi e abbreviazioni al primo utilizzo; se necessario, fornisci un link esterno che fornisca ulteriori informazioni
- Usa frasi brevi e spezza il testo utilizzando paragrafi più brevi, intestazioni ed elenchi
- Puoi usare
**grassetto**e corsivo per evidenziare frasi o parole chiave, ma non abusarne - Evita di usare gergo o termini tecnici senza spiegazioni: in caso di dubbio, propendi per spiegare
- Usa screenshot quando descrivi un’interfaccia visiva, come un elemento dell’interfaccia utente (UI)
- Non documentare o tentare di rivelare funzionalità, prodotti o servizi futuri di Discourse a meno che non sia esplicitamente consentito
- Usa parole di transizione come quindi, sebbene e inoltre
- Usa contrazioni comuni: è, ti sarà, sei, siamo, facciamo
- Inferisci la timelessità nella documentazione: evita parole come presto, nuovo, ora, ultimo, ecc., che diventano rapidamente irrilevanti
- Non attribuire qualità umane a software o hardware
- Es. “Se passi un intero a questa API, si arrabbierà e lancerà un errore”
- Es. “Il nostro amichevole e ambizioso bot AI ti aiuterà a risolvere tutti i tuoi problemi”
- Quando citi del testo (incluso dall’interfaccia utente di Discourse), usa le “virgolette”
- Quando citi un URL, usa i
backticks - Quando usi un dominio di esempio, usa
discourse.example.com - Se utile, puoi usare emoji all’inizio di un paragrafo per evidenziarlo. Non usarne più di due o tre in un singolo argomento. Alcune emoji esempio che puoi usare:
- - Una nota informativa
- Annuncio o avviso
- Un messaggio di avviso
- Informazioni molto importanti
- Evita:
- Metafore o umorismo non necessari
- Riferimenti culturali e regionali
- Istruzioni o ordini in un tono condiscendente: es. Devi cliccare Pubblica o Hai bisogno di cliccare Pubblica
- Essere eccessivamente gentili. Per esempio, Per favore clicca Pubblica
- Usare punti esclamativi a meno che non siano assolutamente necessari
- Maiuscole dove non necessarie
- Uso eccessivo delle stesse frasi e pronomi
Per la documentazione per utenti finali:
Mantieni un tono amichevole e informale, con un focus sulla chiarezza e concisione in modo competente. Vai dritto al punto. Spiega i termini tecnici, ma fai attenzione a non essere condiscendente. Per garantire la chiarezza, inizia specificando brevemente il contesto dell’argomento corrente.
Per la documentazione per sviluppatori e tecnica:
Mantieni un tono diretto e preciso. Usa lo stesso tono che useresti per la documentazione per utenti, ma puoi presupporre un livello di conoscenza tecnica più elevato nei tuoi lettori.
Struttura
- Vai dritto al punto: inizia con ciò che è più importante
- Includi parole chiave importanti all’inizio del documento
- Rendi ovvie le scelte del lettore e i prossimi passi
- Usa sempre un markup leggero per scrivere la documentazione (Questo è già integrato in Discourse con Markdown-it).
- Riferimento per l’uso: https://markdown-it.github.io/
- Organizza la tua documentazione in un flusso logico: inizia con una panoramica, seguita da sezioni dettagliate e, se applicabile, una sintesi o conclusione
- Usa intestazioni e sottointestazioni per strutturare il tuo contenuto, rendendolo più facile da scansionare e trovare informazioni specifiche: usa una gerarchia discendente nelle intestazioni, iniziando con h2, e non saltare livelli
- Fornisci link ad argomenti o sezioni correlati all’interno della tua documentazione: questo aiuta gli utenti a trovare informazioni aggiuntive senza ricerche inutili
Link
- Usa testo significativo nei link
- A meno che il formato dell’URL non sia importante o istruttivo, non usare un URL come testo del link: usa invece il titolo della pagina o una descrizione della pagina
- Collega a siti e fonti esterni invece di citare o riscrivere documentazione esistente
- Assicurati che i siti a cui colleghi siano di alto standard e qualità
- Se il link scarica un file, menzionalo esplicitamente: indica anche il tipo di file scaricato e una stima approssimativa delle dimensioni del file
Codice nella documentazione
- Usa blocchi di codice con evidenziazione della sintassi specifica del linguaggio quando possibile per esempi di codice di grandi dimensioni
- Se non è già autoesplicativo, introduci un esempio di codice con una frase introduttiva che innesca l’esempio che segue: in caso di dubbio, propendi per spiegare
- Gli esempi di codice devono seguire le migliori pratiche per la scrittura di codice nel linguaggio di programmazione rilevante
- Usa il codice in linea per esprimere attributi di base del codice o quando un blocco di codice completo non è necessario, come:
- Nomi e valori degli attributi
- Nomi delle classi
- Nomi di utility da riga di comando
- Tipi di dati
- Nomi di variabili d’ambiente
- Nomi di file, estensioni di file e percorsi
- Cartelle e directory
- Verbi HTTP, codici di stato e valori content-type
- Nomi e valori dei parametri di query
- Input di testo
- Quando usi un segnaposto negli esempi di codice, comandi o altro testo, includi una spiegazione di cosa rappresenta il segnaposto
- Scrivi una spiegazione la prima volta che usi il segnaposto; se ci sono più segnaposti o passaggi dopo il primo utilizzo di quel segnaposto, puoi spiegare di nuovo il segnaposto
- Fornisci un modo semplice per utenti o sviluppatori per copiare ed eseguire il codice.
- Mostra l’output atteso, sia in una sezione separata dopo l’esempio di codice o usando commenti nel codice nell’esempio
- Scrivi codice sicuro: non inserire mai password, chiavi API o informazioni sensibili nel codice
Procedure e guide passo-passo
- Formatta le procedure in modo coerente, in modo che i lettori possano trovarle facilmente scansionando
- Usa una voce numerata separata per ogni passaggio
- Includi azioni che completano un passaggio, come i pulsanti OK o Applica
- Se l’istruzione appare nella stessa interfaccia utente dove avviene l’azione, di solito non è necessario fornire dettagli sulla posizione
- Se devi assicurarti che il lettore inizi nel posto giusto, fornisci una breve frase all’inizio del passaggio
Accessibilità e inclusività
- Usa screenshot, diagrammi o video quando aggiungono valore, in particolare per spiegare passaggi complessi o mostrare parti di un’interfaccia
- Le immagini dovrebbero essere usate per supportare le informazioni testuali, non per sostituirle
- Usa sempre attributi
altper le immagini - Fornisci sempre didascalie o trascrizioni per i video
- Usa GIF solo se puoi spiegare completamente il contenuto nel testo
- Scegli immagini semplici e taglia i dettagli superflui
- Usa un linguaggio semplice ed evita figure retoriche o modi di dire che potrebbero non essere universalmente compresi
- Considera che il tuo documento sarà utilizzato su una moltitudine di dispositivi
- Usa un linguaggio neutro rispetto al genere. Non usare lui, lui, suo, lei, sua quando ti riferisci alle persone: per scrivere evitando i pronomi, puoi:
- Riscrivere usando la seconda persona (tu)
- Riscrivere la frase usando un sostantivo plurale e un pronome plurale
- Usare le parole persona o individuo
- Usare gli articoli il, lo, la, un, una invece di un pronome
- Usare un pronome plurale come loro, loro, o essi, anche se si riferisce a un singolo individuo
- Quando scrivi di una persona reale, usa i pronomi preferiti da quella persona
- Sii inclusivo riguardo all’identità di genere, razza, cultura, religione, abilità, età, orientamento sessuale e classe socioeconomica: includi una vasta gamma di professioni, culture, contesti educativi, località e contesti economici negli esempi
- Evita contenuti politicizzati: nei casi in cui sia necessario includere contenuti politici, mantieni la neutralità
- Non fare generalizzazioni su persone, paesi e culture, nemmeno generalizzazioni positive o neutrali
- Non scrivere contenuti pregiudizievoli e discriminatori contro qualsiasi comunità, specialmente le minoranze
- Evita termini qualitativi legati a eventi storici
- Evita di usare termini e metafore associati a violenza e azioni militari
.
). Ottimo punto sull’incoerenza, però. Non sono sicuro su quale atterreremo, ma ci assicureremo sicuramente di sceglierne una e di attenerci ad essa. 