Come scrivere istruzioni chiare passo passo per il software

Istruzioni software chiare permettono al lettore di completare un'attività senza doversi concentrare sulle istruzioni. Ogni parola in più, ogni etichetta vaga o ogni passaggio che ne unisce due lo costringe a rileggere.

Questo articolo descrive le regole di scrittura più importanti, con esempi, e mostra come applicarle quando crei una guida in Temposhot su Mac.

Definisci un risultato finito

Scrivi per primo il risultato, in una frase che il lettore può verificare: "La fattura viene inviata al cliente e contrassegnata come Sent." Questa frase diventa il titolo e l'ultimo passaggio.

Se non riesci a scrivere un solo risultato, le istruzioni coprono più di un'attività. Dividile. Chi cerca "invia una fattura" non vuole scorrere fino a "crea un cliente".

Scrivi il risultato prima del primo screenshot. Un risultato scritto dopo la registrazione tende a descrivere la registrazione, con ogni clic che l'autore ha fatto per caso. Un risultato scritto per primo decide quali clic appartengono alla guida. I clic che servono solo a passare da una schermata all'altra, come aprire un menu per raggiungere la pagina giusta, di solito si possono sostituire con un'unica etichetta che indica la destinazione.

Quando un'attività richiede due ruoli, scrivi due guide con un risultato ciascuna. Una guida per chi approva una fattura e una per chi la invia hanno punti di partenza e controlli diversi. Unirle costringe ogni lettore a saltare le parti che non riguardano il suo ruolo.

Risultato vago e risultato verificabile

Un risultato è verificabile quando il lettore può guardare lo schermo e rispondere sì o no. Il confronto sotto mostra la stessa attività scritta in due modi.

La versione verificabile definisce anche la lunghezza della guida. Una guida che termina con uno stato visibile ha un ultimo passaggio naturale, quindi chi scrive non aggiunge un paragrafo di chiusura che ripete il primo.

Inizia ogni passaggio con l'azione

Il lettore cerca il verbo. Mettilo all'inizio.

Debole	Chiaro
Il menu Settings dovrebbe ora essere aperto.	Apri Settings.
Successivamente vorrai fare clic su Save.	Seleziona Save.
Nell'angolo in alto a destra c'è un pulsante Share.	Seleziona Share nell'angolo in alto a destra.
Assicurati che le notifiche siano disattivate.	Disattiva Notifications.

Usa una lista breve di verbi e mantienila coerente: Apri, Seleziona, Scegli, Inserisci, Attiva, Disattiva, Trascina. "Clic" funziona per chi usa il mouse ma non per chi usa la tastiera o il touch, quindi molte guide di stile preferiscono "Seleziona".

Usa il modo imperativo in ogni passaggio. "Seleziona Save" e "Apri Settings" dicono al lettore cosa fare adesso. "Dovresti selezionare Save" aggiunge un livello che il lettore deve eliminare prima di agire. La stessa regola vale per la frase di risultato alla fine di un passaggio, che descrive ciò che lo schermo mostra: "Il banner mostra Changes saved."

Un verbo per ogni tipo di controllo

Una lista di verbi funziona solo se ogni verbo corrisponde a un tipo di controllo. Un lettore che vede "Scegli" si aspetta un elenco o un menu, e un lettore che vede "Seleziona" si aspetta un pulsante o un link. La checklist sotto assegna una regola a ogni verbo.

Quando un controllo non corrisponde ad alcun verbo dell'elenco, descrivi la sua posizione e la sua etichetta. Un controllo che apre un selettore va con "Scegli", un controllo che avvia un processo va con "Seleziona". Mantieni l'elenco breve, perché ogni nuovo verbo è una regola in più da ricordare a chi scrive.

Usa le etichette esatte dell'interfaccia

Copia le etichette esattamente come le mostra l'interfaccia, incluse maiuscole e punteggiatura. Se il pulsante dice Add member, non scrivere "Aggiungi un utente". I lettori cercano sullo schermo le parole che leggono.

Metti l'etichetta in grassetto per distinguerla dal resto della frase. Indica la posizione solo quando l'etichetta è difficile da trovare o compare due volte: "Seleziona Export nella barra degli strumenti, non nel menu File".

Etichette che compaiono due volte

Un'etichetta presente in due punti porta il lettore nel posto sbagliato quando il passaggio nomina solo l'etichetta. Una finestra di dialogo spesso ripete il pulsante della barra degli strumenti con la stessa parola, quindi un passaggio che dice solo "Seleziona Export" può riferirsi a entrambi i controlli. La soluzione è indicare il punto a cui il passaggio si riferisce e dire che cosa il lettore deve vedere dopo. "Seleziona Export nella barra degli strumenti. Si apre la finestra di dialogo di esportazione." La seconda frase conferma che il lettore ha il controllo giusto prima di proseguire.

I menu aggiungono un secondo problema. Una voce di menu chiamata Settings può esistere nel menu dell'app e nella barra degli strumenti della finestra. Scrivi il percorso solo quando il lettore ne ha bisogno, e scrivilo una sola volta, nel passaggio che usa per la prima volta il menu.

Regole sulle etichette per la ricerca del lettore

Un lettore che non trova un'etichetta spesso cerca sullo schermo il testo esatto. Una parafrasi lo porta nel posto sbagliato o a nulla. La tabella mostra le regole in uso.

Un'etichetta che cambia tra le versioni dell'app richiede una nota. Indica la versione nella descrizione della pagina, per esempio "Nella versione 4, il pulsante riporta Invite." La nota risponde alla domanda prima che il lettore la faccia.

Una decisione per passaggio

Un passaggio deve contenere una sola azione o una sola scelta. "Apri Settings, seleziona Billing e cambia il piano" sono tre passaggi. Quando il lettore torna allo schermo, perde il punto in una frase lunga.

Eccezione: due azioni nella stessa piccola area che vanno sempre insieme, come "Inserisci il codice e seleziona Verify". Anche in questo caso, dividile se la seconda azione dipende da una condizione.

I passaggi decisionali richiedono la stessa cura. Quando il lettore deve scegliere tra più opzioni, elencale nel passaggio oppure indica l'impostazione che controlla la scelta. "Scegli un formato" lascia al lettore il compito di indovinare le opzioni. "Scegli PDF o PNG in Format. Scegli PDF per la stampa" fornisce una regola che il lettore può applicare senza rileggere.

Dividi un passaggio composto

Un passaggio composto nasconde di solito un punto di decisione. L'esempio sotto parte da un passaggio che modifica un abbonamento e lo divide in corrispondenza di ogni azione che il lettore deve confermare.

La prima versione della frase aveva sei verbi e una sola conferma. I quattro passaggi sopra hanno una sola azione ciascuno, e l'ultimo passaggio contiene un checkpoint, di cui parla la sezione successiva.

Aggiungi checkpoint dopo le azioni importanti

Dopo un'azione che modifica qualcosa, indica al lettore cosa deve vedere: "Un banner verde mostra Changes saved." I checkpoint confermano l'avanzamento e intercettano gli errori subito, prima che il lettore sia avanti di cinque passaggi.

Inserisci i checkpoint dopo i salvataggi, gli invii, le importazioni, le richieste di autorizzazione e qualsiasi operazione che richiede tempo di caricamento.

Percorsi di errore

Un checkpoint indica al lettore come si presenta il successo. Un percorso di errore indica come si presenta il fallimento e dove andare dopo. Scrivi un percorso per ogni checkpoint che può fallire. Il percorso indica il messaggio visibile, l'azione da compiere e il passaggio a cui tornare.

Prendi un passaggio di caricamento. Il checkpoint di successo dice "Il nome del file compare nell'elenco". Il percorso di errore dice: "Se l'elenco mostra Upload failed, seleziona Try again. Se fallisce di nuovo, vai alla pagina di risoluzione dei problemi per i limiti di dimensione dei file." Il lettore vede il messaggio, sa quale azione compiere e sa quando fermarsi.

Mantieni brevi i percorsi di errore. Un percorso con tre diramazioni va in una guida separata per la risoluzione dei problemi, collegata dal passaggio. Un percorso che richiede più di una schermata per essere spiegato è di solito due attività.

Dove inserire i checkpoint in una guida lunga

Una guida senza checkpoint fallisce tardi, dopo che il lettore ha fatto diverse modifiche che ora deve annullare. I numeri sotto descrivono una guida di esempio da 12 passaggi, con i checkpoint posizionati dove la prossima azione del lettore dipende da un risultato.

Un checkpoint che descrive un risultato visibile è più utile di uno che dice "Done". "Done" non conferma nulla sullo schermo. "La riga mostra Imported con 240 record" offre al lettore un numero da confrontare con il proprio schermo.

Scrivi le diramazioni a partire da condizioni osservabili

Le diramazioni sono il punto in cui i lettori si perdono. Basale su qualcosa che il lettore può vedere, non su qualcosa che deve sapere.

• Debole: "Se sei sul piano legacy, ..."
• Chiaro: "Se la pagina mostra Upgrade to continue, vai al passaggio 7."

Mantieni brevi le diramazioni. Se una diramazione ha più di due passaggi, spostala in una guida separata e collegala.

Evita le diramazioni che dipendono dalla cronologia del lettore. "Se ti sei registrato prima del 2025" chiede al lettore di ricordare qualcosa che lo schermo non mostra. Sostituiscila con il risultato visibile: "Se la pagina dell'account mostra il badge Legacy, vai al passaggio 7." Una diramazione basata sullo schermo funziona per un nuovo lettore, per chi torna e per un addetto al supporto che consulta la guida per un'altra persona.

Una diramazione che parte da una schermata

Il flusso sotto mostra una diramazione che il lettore può verificare sullo schermo. Il lettore non deve sapere quale piano ha.

La diramazione riporta il lettore a un punto noto. Il passaggio 9 chiude la guida per chi non può esportare, così gli altri lettori non devono saltarlo.

Usa gli screenshot per mostrare posizione e stato

Il testo dice cosa fare. Lo screenshot mostra dove si trova il controllo e com'è fatto. Usane uno per passaggio, ritagliato sull'area che conta, con un solo segno sul bersaglio. Lo screenshot conferma anche lo stato: il lettore confronta il proprio schermo e capisce di essere sulla strada giusta.

Temposhot crea questa coppia a partire dai tuoi clic. Apri Action Capture (Command+3), attiva Parse clicked elements sotto Configure e seleziona Start Action Capture. Ogni clic accettato salva la schermata appena prima del clic, con un titolo di bozza come Click "[[element-name]]". Dopo Finish capture, il Document si apre nell'editor.

Ritaglia ogni screenshot sulla finestra o sul controllo che il passaggio nomina. Una schermata intera mostra molti controlli, e il lettore deve trovare quello indicato dal passaggio. Prima dell'esportazione, controlla che il ritaglio non mostri dati privati, come il nome di un account o una notifica non pertinente, e verifica l'immagine alla dimensione in cui sarà stampata o visualizzata.

Riscrivi ogni titolo di bozza con le regole sopra, per esempio da Click "Save" a "Seleziona Save per conservare le modifiche". Inserisci checkpoint e condizioni nella Page description. Nell'esportazione PDF, le descrizioni possono comparire prima o dopo ogni screenshot (una personalizzazione Pro). La guida all'editor copre titoli, descrizioni e strumenti.

Impostazioni per una guida pratica

Le impostazioni sotto producono una pagina per clic con un bersaglio visibile. Corrispondono a una guida scritta per un lettore che lavora su una sola finestra.

Usa la scorciatoia manuale per una schermata che cambia senza un clic, come uno stato che si aggiorna dopo l'elaborazione. Attiva Show cursor in shortcut captures per questi passaggi, così il puntatore indica il campo che il lettore deve leggere.

Mantieni lo stesso target di acquisizione in tutta la guida. Passare da Active Window a Specific Window a metà guida rende incoerente l'inquadratura delle pagine.

Tasti dell'editor per scrivere le pagine dei passaggi

La maggior parte delle modifiche avviene nell'editor, una pagina alla volta. I tasti sotto coprono le azioni usate più spesso per scrivere titoli, descrizioni e segni.

Rimuovi riempitivi e presupposti impliciti

Elimina le parole che non cambiano ciò che il lettore fa:

• "Semplicemente", "solo", "facilmente": non aggiungono nulla e fanno sentire in difficoltà chi sta cercando di seguire.
• "Adesso vorrai", "Vai avanti e": inizia con il verbo.
• "Come detto sopra": ripeti il fatto o collegalo.

Poi cerca i presupposti. Il lettore sa dove si trova l'app, quale account usare, che cosa significa un termine? Aggiungi una riga per ogni lacuna, di solito nei prerequisiti.

Misura il taglio

I riempitivi sono facili da aggiungere e facili da non notare. Contare le parole prima e dopo una modifica mostra quanto una sola revisione elimina.

Il taglio fa più che accorciare la pagina. Ogni frase eliminata era un punto in cui il lettore si fermava a chiedersi se fosse importante. Il passaggio modificato si legge come un'istruzione già alla prima lettura.

Testa le istruzioni senza spiegarle

Dai le istruzioni a qualcuno che non ha mai svolto l'attività. Osservalo mentre segue le istruzioni, senza rispondere alle domande. Ogni pausa o domanda indica un passaggio che richiede un'azione, un'etichetta o un checkpoint più chiari.

Scegli tester che corrispondano ai lettori. Un tester che ha costruito il prodotto conosce le etichette e il flusso, quindi una sessione pulita dimostra poco. Un tester del team di supporto o un nuovo assunto nel ruolo di destinazione trova le lacune che l'autore non vede più. Dai al tester la guida e l'account che userà, e nient'altro.

Correggi quei passaggi e ripeti il test con un'altra persona, se possibile. Due sessioni pulite sono un buon segno che le istruzioni funzionano. La checklist per i tutorial con screenshot elenca i controlli rimanenti prima della pubblicazione.

Svolgi una sessione con appunti

Annota l'orario e il numero del passaggio per ogni pausa, e lascia le spiegazioni per dopo la sessione. La timeline sotto mostra una sessione su una guida di nove passaggi con un risultato utile.

Gli appunti mostrano quali passaggi richiedono etichette e quali un checkpoint. Una singola sessione mostra una tendenza, non un tasso, quindi svolgi una seconda sessione prima di modificare di nuovo la guida.

File conservati con una guida pratica

Una guida ha più file delle sue pagine. Il Document di origine resta nella libreria Documents, mentre il PDF esportato e gli appunti vanno in un'unica cartella fuori dall'app. La cartella conserva il numero di versione e gli appunti dei test accanto al file che ricevono i lettori, così la modifica successiva parte dalla stessa registrazione.

Domande frequenti

Nelle istruzioni devo usare "clic" o "seleziona"?

"Seleziona" funziona per mouse, tastiera e touch. Usa "clic" solo se il pubblico usa il mouse e la guida di stile lo preferisce. Qualunque termine scegli, usalo in modo coerente.

Quanto deve essere lungo un passaggio?

Una frase per l'azione, più una frase facoltativa per il risultato o la condizione. Le spiegazioni più lunghe vanno in una nota o in una pagina separata.

Le istruzioni devono avere passaggi numerati?

Sì, quando l'ordine conta. I numeri permettono ai lettori di non perdere il punto e al supporto di citare "passaggio 4". L'esportazione PDF di Temposhot può aggiungere i numeri dei passaggi (Pro).

Dove vanno le avvertenze?

Prima del passaggio a cui si riferiscono. Un'avvertenza dopo un'azione distruttiva arriva troppo tardi.

Quanti screenshot servono in una guida?

Uno per ogni passaggio in cui cambia la schermata o il bersaglio è difficile da trovare. Un passaggio che si limita a digitare testo in un campo già visibile non ne richiede uno. Conta gli screenshot rispetto ai passaggi dopo la prima bozza e rimuovi quelli che ripetono la stessa schermata.

Che cosa succede se l'interfaccia cambia dopo la pubblicazione?

Trova ogni passaggio che nomina un'etichetta o una posizione cambiata, e aggiorna insieme lo screenshot e il titolo. Un nuovo screenshot con un'etichetta vecchia confonde il lettore più di quanto lo facesse lo screenshot precedente. Registra la versione dell'app nella descrizione della pagina o nel piè di pagina della guida, così i lettori possono capire a quale versione si riferisce.

Come scrivo per chi usa solo la tastiera?

Indica il tasto o il bersaglio del focus quando il passaggio dipende da essi, per esempio "Premi Tab finché il pulsante Export non ha il focus". Non fare affidamento sulla parola "clic" o sulla posizione di un controllo sullo schermo, perché chi usa la tastiera non vede la posizione allo stesso modo. Prova una sessione solo con la tastiera prima di pubblicare.

Quanti checkpoint bastano?

Uno dopo ogni azione che salva, invia, importa o modifica l'accesso, e uno dopo ogni passaggio che richiede più di qualche secondo. Troppi checkpoint rallentano il lettore, quindi unisci i checkpoint di due azioni che avvengono sempre insieme.

Trasforma i tuoi clic in una guida passo passo chiara

Action Capture crea uno screenshot e un titolo di bozza per ogni clic, pronti per queste regole di scrittura. Scarica Temposhot e scrivi la tua prossima guida partendo da una registrazione.