Questa guida fornisce istruzioni su come scrivere efficaci guide “come fare” per Discourse. Copre elementi essenziali come struttura e stile, considerazione del pubblico e manutenzione.
Livello utente richiesto: Chiunque può scrivere nuove guide “come fare”
Scrivere efficaci guide “come fare” è fondamentale per aiutare utenti, moderatori, amministratori e sysadmin a eseguire varie attività all’interno di Discourse. Questa guida ti aiuterà a creare guide chiare e utili per la comunità .
Riepilogo
In questa documentazione imparerai:
- Perché è importante scrivere una guida “come fare”
- Quali informazioni includere
- Linee guida per struttura e stile
- Dove pubblicare questi argomenti
- Come mantenerli dopo la pubblicazione
Perché scrivere una guida “come fare”?
Ti è mai capitato di dover eseguire un’attività e non ricordare come farla? Scrivere un documento “come fare” è un ottimo modo per documentare i processi in Discourse. Se hai difficoltà con un processo specifico, è probabile che lo abbia anche qualcun altro. Documentarlo aiuta tutti.
Scopri di più su cosa rende una guida “come fare” diversa da altri tipi di documentazione, come tutorial o guide di riferimento, in questa guida di Divio.
Scrivere o revisionare una guida “come fare” è un ottimo modo per iniziare a contribuire con le tue conoscenze su Discourse alla comunità . Per altri modi per contribuire, consulta la guida su come contribuire a Discourse.
Quali informazioni includere?
Una guida “come fare” dovrebbe essere una guida passo dopo passo che porta l’utente a un risultato specifico. Ad esempio, una guida intitolata “Configurazione di HTTPS per Discourse” dovrebbe fornire istruzioni per configurare HTTPS.
Punti chiave da ricordare quando si scrive una guida “come fare”:
- Attieniti all’argomento ed essere chiaro
- Evita informazioni non necessarie
- Sii conciso ma informativo
- Spiega perché raggiungere il risultato finale è vantaggioso
Considera il tuo pubblico
Ci sono diversi pubblici per le guide “come fare” di Discourse, ognuno dei quali richiede un livello di spiegazione diverso. Usa le categorie di documentazione come guida su chi prendere di mira con la tua guida:
- Documentation > Using Discourse
- Documentation > Site Management
- Documentation > Integrations
- Documentation > Hosted Customers
- Documentation > Self-Hosting
- Documentation > Migrating to Discourse
- Documentation > Developer Guides
- Documentation > Contributing
Comprendi il livello di competenza tecnica del tuo pubblico e adatta la tua guida di conseguenza. Alcuni suggerimenti:
- Evita passaggi che il pubblico non può eseguire (ad esempio, i clienti ospitati generalmente non hanno accesso ai comandi della console)
- Mantieni le istruzioni chiare ed evita un linguaggio altamente tecnico per utenti non tecnici
- Non aggiungere informazioni di base che il tuo pubblico dovrebbe giĂ conoscere
Struttura e stile
La guida di stile per la documentazione copre tutto ciò che devi sapere su come strutturare e stilizzare le guide “come fare” (e tutte le altre documentazioni di Discourse):
Pubblicazione di una guida
Pubblica le guide in una sottocategoria della categoria padre Documentation e taggale con how-to. Tutte le guide richiedono l’approvazione del team di Discourse, che verrà gestita automaticamente attraverso il processo di moderazione. La guida di stile descrive ogni categoria in modo più dettagliato per aiutarti a decidere dove pubblicare la tua guida.
Mantenimento della tua guida
Una volta pubblicata una guida “come fare”, tienila aggiornata. Ecco come puoi contribuire a mantenerla:
- Tieni d’occhio le risposte — Integra i feedback della comunità nella guida.
- Testa la guida personalmente — Segui periodicamente la guida per assicurarti che sia ancora accurata.
- Modifica informazioni mancanti o errate — Se sei al Livello di Fiducia 2 o superiore, modifica il primo post della guida “come fare”.
- Segnala gli argomenti per assistenza — Se non puoi apportare una modifica, segnala il post con “Qualcos’altro” e spiega cosa è necessario.
Nella maggior parte dei casi, i commenti alle guide “come fare” ufficiali verranno eliminati dopo un mese per mantenere il focus sulla guida stessa.
Grazie per aver contribuito a migliorare la documentazione della comunità Discourse! Se sei bloccato, non esitare a chiedere aiuto. Il modo migliore per iniziare è contribuire e imparare lungo il cammino.