Come scrivere istruzioni software passo passo chiare

Una documentazione visiva chiara per un software spiega al lettore che cosa fare, dove farlo e come capire se ha funzionato. Definisci un solo risultato finale, scrivi azioni dirette con le etichette esatte dell'interfaccia, aggiungi punti di controllo visibili, abbina il testo a screenshot utili e infine prova la guida senza spiegarla a voce.

In breve: inizia ogni passaggio con l'azione, indica il comando visibile, includi il valore o la condizione necessari e dichiara il risultato che permette al lettore di proseguire.

Definisci un solo risultato finale

Il risultato dà uno scopo a ogni passaggio. Descrivi l'attività come qualcosa che il lettore può completare e verificare, per esempio «Esporta la guida come file PNG» oppure «Abilita per Shotomatic l'autorizzazione alla registrazione dello schermo».

Evita obiettivi ampi come «Impara a usare l'editor». Un obiettivo generico non dice all'autore che cosa includere né al lettore quando ha finito.

Inizia ogni passaggio con l'azione

La prima frase deve dire al lettore che cosa fare. Comincia con un verbo diretto, come apri, seleziona, inserisci, trascina, controlla o esporta.

Confronta queste due versioni:

Prima: «Il menu di esportazione si trova nell'angolo in alto a destra e contiene diversi formati utili».

Dopo: «Apri il menu Export nell'angolo in alto a destra».

La seconda versione permette al lettore di agire subito. Una spiegazione sui formati può seguire soltanto se cambia la scelta.

Usa le etichette esatte dell'interfaccia

Le etichette esatte aiutano il lettore ad associare l'istruzione alla schermata attuale. Rispetta le maiuscole visibili e distingui tra menu, pulsante, campo, scheda e scorciatoia da tastiera quando cambia l'interazione.

Prima: «Vai nelle impostazioni e abilita l'autorizzazione pertinente».

Dopo: «Apri System Settings > Privacy & Security > Screen & System Audio Recording, quindi abilita Shotomatic».

Evita i nomi interni del prodotto che il lettore non può vedere. La documentazione deve seguire l'interfaccia pubblica, salvo quando è destinata esplicitamente a sviluppatori o amministratori.

Mantieni una decisione per passaggio

Ogni passaggio deve contenere un'azione o una decisione significativa. In questo modo è più facile individuare gli errori e associare gli screenshot.

Digitazione e conferma strettamente collegate possono rimanere insieme:

Inserisci Revisione trimestrale in Document title, quindi seleziona Save.

Dividi il passaggio quando una delle azioni ha un avviso, un risultato atteso o una diramazione propri.

Aggiungi punti di controllo dopo le azioni importanti

I punti di controllo spiegano al lettore se l'azione è riuscita. Usali dopo modifiche alle autorizzazioni, caricamenti, esportazioni, inviti, azioni distruttive e transizioni che possono richiedere tempo.

Prima: «Seleziona Export PDF e continua».

Dopo: «Seleziona Export PDF. Quando si apre la finestra di salvataggio, scegli la cartella di destinazione».

Il punto di controllo evita che il lettore cerchi una cartella mentre l'applicazione mostra ancora la schermata precedente.

Scrivi le diramazioni a partire da condizioni osservabili

Le diramazioni devono iniziare con qualcosa che il lettore può vedere o verificare. Indica prima il percorso normale e mantieni l'eccezione vicino al passaggio che modifica.

Prima: «Se necessario, regola le autorizzazioni».

Dopo: «Se l'anteprima della finestra è vuota, apri System Settings > Privacy & Security > Screen & System Audio Recording e verifica che Shotomatic sia abilitato».

Non aggiungere alla guida principale ogni rara eccezione. Rimanda a una pagina mirata per la risoluzione dei problemi se diversi sintomi e cause interromperebbero l'attività.

Lascia che gli screenshot mostrino posizione e stato

Testo e immagine devono dividersi il lavoro. Il testo comunica azione, valore richiesto, condizione e risultato atteso. Lo screenshot mostra la posizione del comando e lo stato visivo pertinente.

Evita un paragrafo che descrive ogni elemento visibile. Evita anche un'immagine che contiene l'intera istruzione come grande testo sovrapposto. Il lettore deve poter capire l'azione anche se l'immagine non è disponibile o è difficile da vedere.

Consulta Come annotare gli screenshot per creare istruzioni chiare su Mac per scegliere indicatori di clic, frecce, forme, testo, ritaglio e sfocatura.

Elimina i riempitivi e le supposizioni nascoste

I riempitivi ritardano l'azione, mentre le supposizioni nascoste la rendono impossibile. Elimina formule come «semplicemente», «basta», «come al solito» e «configura secondo necessità». Sostituiscile con il requisito mancante.

Prima: «Configura semplicemente le opzioni di esportazione secondo necessità».

Dopo: «Scegli PNG, mantieni Original size e seleziona la cartella in cui il ticket di assistenza conserva le prove».

La riscrittura è più lunga perché contiene le informazioni necessarie al lettore. Essere concisi significa eliminare le parole inutili, non i dettagli indispensabili.

Prova le istruzioni senza spiegarle

La prova deve coinvolgere una persona che non ha partecipato alla scrittura della guida. Forniscile le condizioni iniziali dichiarate e chiedile di completare l'attività senza correzioni verbali.

Annota il primo punto in cui esita, sceglie il comando sbagliato o raggiunge uno stato imprevisto. Correggi in quel punto l'istruzione o lo screenshot, poi ripeti la prova dall'inizio.

La guida è pronta quando il lettore raggiunge il risultato dichiarato, ogni diramazione è osservabile e i passaggi non dipendono dalla memoria dell'autore. Per l'intero flusso di acquisizione dei clic, consulta Come creare una guida passo passo dai clic su Mac e controlla gli strumenti attuali di Action Capture.