User Documentation In questo tutorial puoi imparare come creare un tutorial.
Un tutorial è una lezione che ti guida attraverso una serie di passi pratici. Offre un'esperienza di apprendimento facendo qualcosa. È il modo migliore per conoscere un argomento che non ti è ancora familiare. I tutorial sono fondamentali in qualsiasi documentazione: accompagnano i nuovi arrivati, guidano i primi passi, sono la vetrina, offrono un'esperienza semplice e piacevole di un argomento. Uno dei "trucchi" per ottenere questo è escludere tutto ciò che può distrarre nel processo di apprendimento. Per esempio:
- Modi alternativi per fare qualcosa o modi per fare qualcosa di molto specifico.
- Riferimenti completi di tutte le opzioni e una descrizione tecnica della loro struttura.
- Spiegazioni dettagliate e contesti storici.
Queste informazioni aggiuntive è meglio fornirle separatamente. Evita il più possibile di mescolarle, perché finirebbero solo per appesantire il tutorial. Questo è il principio fondamentale del framework Diátaxis, un modo sistematico per migliorare la documentazione. Inserisci le informazioni aggiuntive sopra menzionate in guide pratiche, riferimenti e spiegazioni appositi. Nelle guide pratiche puoi trovare rapidamente come fare qualcosa di specifico. Nei riferimenti puoi consultare come funzionano le cose, quali opzioni hanno e dove trovare maggiori informazioni. Con le spiegazioni puoi approfondire la tua comprensione dell'argomento.
Sebbene un tutorial offra un'introduzione a un argomento, non è rivolto esclusivamente ai principianti. Può anche essere un'introduzione a un argomento avanzato! Chiarisci all'inizio del tuo tutorial quali conoscenze o abilità sono necessarie per poterlo svolgere.
Se insegni a qualcuno a cucinare, devi spiegare cose come le tecniche di taglio, come usare un forno e altre nozioni base di cucina. Inizi con una ricetta semplice, preferibilmente qualcosa che dia facilmente un buon risultato finale. Quel risultato finale di per sé non è l'obiettivo principale: vuoi insegnare delle abilità. Questo è ciò che fa un tutorial. Chi sa già cucinare e vuole realizzare qualcosa di specifico non ha bisogno di un tutorial del genere, ma di una ricetta. Le ricette sono le guide pratiche della cucina.
Passo dopo passo
Per creare un tutorial:
- Raccogli informazioni sull'argomento. Documentazione esistente, video, ecc. Annota le cose che trovi confuse o che ti hanno richiesto del tempo per essere comprese. Ci sono domande sull'argomento nel forum?
- Quali concetti sono coinvolti? Fare uno schizzo con un piccolo diagramma può aiutare. Non cercare di essere completo, ma chiarisci cosa è importante per questo tutorial e cosa no.
- C'è qualche conoscenza o abilità specifica necessaria da insegnare nel tuo tutorial?
- Crea un esempio in cui puoi utilizzare tutti i concetti e le abilità che vuoi trasmettere nel tutorial. Rendi l'esempio il più semplice possibile.
- Definisci e scrivi i passi per arrivare a un risultato finale. Ogni passo dovrebbe essere riproducibile dal tuo studente.
- Filtra tutte le spiegazioni, riferimenti, alternative e casi particolari; mettili in articoli separati.
- Scrivi un'introduzione. Cosa imparerai in questo tutorial? Menziona eventuali prerequisiti necessari per svolgere il tutorial.
- Scrivi il riepilogo. Cosa abbiamo imparato? Puoi anche menzionare quali passi successivi intraprendere per approfondire.
- Aggiungi screenshot con annotazioni per illustrare le azioni da intraprendere. Suggerimento: usa dei numeri nello screenshot e fornisci le spiegazioni nel testo. Questo rende più facile riutilizzare lo screenshot nelle traduzioni e riduce al minimo lo sforzo per produrre screenshot specifici per lingua.
- Aggiungi diagrammi per spiegare strutture, relazioni e processi.
- Aggiungi gli articoli di accompagnamento con spiegazioni, riferimenti e guide pratiche.
- Metti tutti gli articoli su un argomento sotto un articolo di panoramica, spiegando cosa è cosa, come si relazionano e da dove iniziare.
Esempio: creare e pubblicare un articolo in Joomla
Come esempio, creiamo un tutorial su come creare e pubblicare un articolo sotto una voce di menu in Joomla.
Raccolta di informazioni
Nel nostro manuale utente troverai articoli pertinenti sotto "Per iniziare", "Articoli" e "Menu". Spesso risulta confuso, quando si inizia con Joomla, non vedere un articolo dopo averlo creato, anche se lo si è contrassegnato come "pubblicato". Per vedere l'articolo, deve esserci un link ad esso. Ci sono diversi modi per creare un tale link (come una voce di menu o un layout blog di categoria o mettendolo nel layout blog della home page contrassegnando l'articolo come in evidenza o collegandolo da un altro articolo), ma ora ci concentreremo sul rendere l'articolo disponibile tramite una voce di menu.
Concetti e abilità
Abbiamo 'contenuto', 'articolo', 'menu' e 'voce di menu'. Dobbiamo chiarire questi termini. Mostriamo dove trovare queste cose nel menu di amministrazione. Tralasciamo 'categorie' o 'in evidenza' in questo tutorial.
Prerequisiti
Devi avere accesso al lato amministratore di un sito Joomla funzionante e sapere come effettuare l'accesso.
Obiettivo
Il nostro obiettivo è imparare come creare un nuovo articolo Joomla e una nuova voce di menu sotto la quale mettere il nostro articolo.
Passi
Usa i seguenti passi per raggiungere il nostro obiettivo:
A. Crea un articolo
- Accedi al tuo pannello di amministrazione Joomla.
- Prima creeremo l'articolo. Vai al menu "Contenuti" sulla sinistra e seleziona "Articoli".
- Clicca su "Nuovo" per creare un nuovo articolo.
- Inserisci un titolo e un contenuto per il tuo articolo.
- Clicca su "Salva e chiudi" per salvare il tuo articolo.
B. Crea una voce di menu che colleghi all'articolo
per mostrare l'articolo sul sito web creeremo una voce di menu che colleghi all'articolo. Vai al menu "Menu" sulla sinistra e seleziona "Menu principale".
- Proprio come con un articolo, clicca su "Nuovo" per creare una nuova voce di menu.
- Inserisci un titolo per la tua voce di menu. Questo è il titolo come apparirà nel menu. Non deve essere necessariamente lo stesso del titolo dell'articolo. Di solito è più corto del titolo di un articolo per adattarsi meglio al menu.
- Seleziona un tipo di voce di menu: sotto "Articoli" seleziona "Articolo singolo".
- Seleziona l'articolo: seleziona l'articolo che abbiamo appena creato.
- Vai al sito web e aggiorna la pagina. Congratulazioni: ora puoi cliccare sulla voce di menu per vedere il tuo articolo.
Introduzione
Scrivi l'introduzione: cosa imparerai in questo tutorial e quali prerequisiti sono necessari.
Filtra le informazioni aggiuntive
Possiamo tralasciare qualcosa di quanto scritto finora? Beh, nel passo 2 della creazione di una voce di menu ho menzionato che il titolo della voce di menu non deve essere necessariamente lo stesso del titolo dell'articolo. È un'aggiunta necessaria per questo tutorial? Se no, allora è meglio tralasciarla per ora. Ma offre uno spunto per un articolo più specializzato sui titoli degli articoli e i titoli dei menu e su quando vengono mostrati, coinvolgendo le opzioni generali degli articoli, le impostazioni individuali dell'articolo nella scheda opzioni, le impostazioni della voce di menu nella scheda opzioni della voce di menu e altro ancora. Sarebbe anche utile creare un articolo di tipo riferimento su come articoli, categorie e voci di menu lavorano insieme; in un articolo del genere cerca di essere completo, elenca tutte le possibilità. Una guida pratica specializzata potrebbe essere: "Come mostrare il titolo dell'articolo?", mostrando le impostazioni nelle impostazioni generali dell'articolo, e nelle impostazioni individuali dell'articolo e della voce di menu. Un articolo di tipo spiegazione potrebbe raccontare qualcosa sul contesto per cui Joomla usa "articolo" dove ad esempio WordPress usa "post" o come l'articolo viene visualizzato nella pagina finale.
Conclusione
Riassumi tutto in un sommario. E menziona alcuni possibili passi successivi per saperne di più (ad esempio: un tutorial su come aggiungere una categoria o una guida pratica sulla scorciatoia salva-nel-menu).
Immagini e grafica
Crea screenshot che mostrino i pulsanti e i campi coinvolti nella creazione di un articolo e di una voce di menu. Evidenzia i pulsanti e i campi coinvolti.
Per chiarezza potresti aggiungere un diagramma che mostri come un articolo viene messo "sotto" una voce di menu.
Aggiungi riferimenti, guide pratiche e spiegazioni
Metti tutte le informazioni e istruzioni aggiuntive in articoli separati.
Panoramica
Se hai più articoli su un argomento, dovresti creare un articolo di panoramica, spiegando come gli articoli si collegano tra loro e da dove iniziare.
Esercizio
Inizia a creare il tutorial sopra su come creare e pubblicare un articolo in Joomla. Il modo migliore per imparare è farlo. Pubblicheremo un esempio di come questo può apparire nell'attuale manuale utente su questo sito. Ma saremmo felici di pubblicare qui la tua versione se riesci a migliorare quella attuale.
(questo articolo è stato pubblicato anche nel Joomla Community Magazine di febbraio 2025)