Come pianificare un set di documentazione software basato su screenshot

Un set di documentazione con screenshot è facile da avviare e difficile da mantenere. Ogni immagine è una copia dell'interfaccia in un giorno preciso, e l'interfaccia continua a cambiare. Pianificare prima di acquisire determina se il set resiste al primo redesign.

Questo articolo spiega come strutturare il set, come definire le regole per gli screenshot e come produrli su Mac con Temposhot. Un esempio pratico attraversa tutte le sezioni: un'app web di fatturazione con cinque aree di prodotto e un tecnical writer che si occupa anche del supporto.

Elenca le domande a cui i lettori devono rispondere

Raccogli domande reali prima di decidere le pagine. Le fonti utili sono i ticket di supporto, le chiamate commerciali, le sessioni di onboarding, i thread interni in chat e i termini di ricerca della documentazione attuale.

Scrivi ogni domanda con le parole del lettore:

• "Come invito un membro del team?"
• "Perché il mio export è vuoto?"
• "Che cosa significa lo stato di sincronizzazione?"
• "Quale piano include i log di audit?"

Raggruppa i duplicati. La lista risultante definisce l'ambito del set. Ciò che non compare nella lista può essere rinviato.

Esempio pratico: dai ticket alla lista delle domande

Il team di fatturazione ha esportato 240 ticket di supporto degli ultimi 90 giorni. La lettura dei soli oggetti e del primo messaggio del cliente ha richiesto circa due ore. Dopo aver unito i duplicati, sono rimaste 52 domande distinte.

Nove domande sono comparse più di dieci volte ciascuna. Queste nove coprivano quasi la metà di tutti i ticket, quindi hanno stabilito l'ordine di lavoro. Le altre 43 domande sono finite in un backlog ordinato per area: fatture, clienti, pagamenti, impostazioni e fatturazione.

Registra le parole che usano i lettori

Conserva il linguaggio del lettore accanto a ogni domanda, anche quando non coincide con l'etichetta dell'interfaccia. Un cliente che scrive "rimuovere una carta" non cercherà "Metodi di pagamento". Il titolo della pagina deve usare l'etichetta del prodotto, mentre la prima frase può ripetere il termine del lettore, così la ricerca trova entrambi.

Annota anche il contesto di ogni domanda: piano, ruolo e dispositivo. "Come rimborso una fattura" posta da un titolare dell'account e la stessa domanda posta da un utente con ruolo di sola lettura portano a pagine diverse. La prima richiede una guida operativa, la seconda una pagina di risoluzione dei problemi sui permessi mancanti.

Rimuovi le domande che la documentazione non può risolvere

Alcuni ticket descrivono un bug o una funzionalità mancante. Una pagina che spiega un bug diventa una soluzione temporanea che sopravvive alla correzione. Nell'esempio, 6 segnalazioni di bug sono state messe da parte durante l'unione, prima di arrivare al conteggio di 52, e sono state inoltrate al team di prodotto invece che al backlog della documentazione.

Altre domande derivano da un'etichetta poco chiara. Se dieci lettori chiedono che cosa significhi "Sync", una pagina di riferimento aiuta, ma un'etichetta più chiara aiuta di più. Invia anche queste domande al team di prodotto e scrivi la pagina solo se l'etichetta resta invariata.

Assegna un tipo di pagina a ogni domanda

Domande diverse richiedono forme di pagina diverse. Mescolarle rende le pagine lunghe e difficili da scorrere.

Tipo di pagina	Risponde a	Screenshot
Guida operativa	"Come faccio X"	Uno per passaggio
Riferimento	"Che cosa significa X"	Una panoramica annotata per schermata
Risoluzione dei problemi	"Perché X non funziona"	Lo stato di errore e la correzione
Concetto	"Come funziona X"	Diagrammi, pochi o nessuno screenshot

Assegna un tipo a ogni domanda della lista. La maggior parte delle domande sul prodotto diventa una guida operativa.

Conta gli screenshot prima di scrivere

Il tipo di pagina determina quante immagini conterrà una pagina. Moltiplica questo valore per il numero di pagine: il risultato è il numero di immagini da aggiornare dopo ogni redesign. Conviene conoscere questo numero prima di aprire qualsiasi strumento di acquisizione.

Nell'esempio, 31 delle 52 domande sono diventate guide operative con una media di 7 passaggi. Dodici sono diventate pagine di risoluzione dei problemi con 2 immagini ciascuna, 6 pagine di riferimento con una panoramica annotata ciascuna, e 3 pagine di concetto senza screenshot.

Le 247 immagini sono il carico di manutenzione reale del set. Un redesign di una sola area di prodotto che interessa un quinto di esse comporta circa 50 sostituzioni, cioè uno o due giorni di lavoro. Conoscere questo numero rende più facile giustificare la politica sugli screenshot descritta più avanti.

Separa le domande che combinano più tipi

Alcune domande contengono due tipi contemporaneamente. "Perché il mio export è vuoto e come lo risolvo" è una pagina di risoluzione dei problemi che rimanda a una guida operativa. Scrivi la pagina di risoluzione con l'errore e la causa, quindi collegala alla guida operativa per la procedura completa.

Definisci una politica per gli screenshot

Decidi una volta per tutte come appaiono gli screenshot e scrivilo. Un set coerente sembra mantenuto e si aggiorna più in fretta.

• Dimensione della finestra: una dimensione fissa per tutte le acquisizioni. Il target Specific Window in Action Capture mantiene la stessa finestra per l'intera esecuzione.
• Tema e lingua: chiaro o scuro, e una sola lingua dell'interfaccia.
• Dati: solo account di esempio e nomi segnaposto.
• Ritaglio: la finestra o il pannello, mai l'intero desktop. Usa Framing con Focus on action su Balanced o Close.
• Segni: un marcatore di clic o una freccia per immagine, con un solo colore di accento.
• Formato: PNG per il testo dell'interfaccia, WebP se il sito richiede file più leggeri.

Definisci anche dove non servono gli screenshot: un'impostazione con un solo campo, un passaggio la cui etichetta è già nel testo, una schermata che cambia a ogni rilascio.

Traduci la politica nelle impostazioni di acquisizione

Una politica scritta serve solo se le impostazioni di acquisizione la rispettano. Configura Action Capture una volta: i valori vengono salvati sul Mac e usati in tutte le esecuzioni successive. Il team dell'esempio ha usato le impostazioni seguenti per tutte le 31 guide operative.

Specific Window mantiene una finestra del browser come target per l'intera esecuzione, così ogni passaggio ha la stessa larghezza in pixel. Disattiva Include toolbar in captures, altrimenti la toolbar flottante compare nelle immagini della documentazione. Lascia disattivato Capture outside clicks, a meno che l'attività non usi una seconda finestra, come un gestore di password.

Imposta i livelli di inquadratura per tipo di pagina

L'inquadratura non modifica l'immagine originale, quindi la politica può indicare un livello e ammettere eccezioni. Le guide operative usavano Balanced (livello 3) come impostazione predefinita, che lascia nella pagina abbastanza contesto perché il lettore trovi il controllo. I controlli piccoli, come un interruttore in un lungo elenco di impostazioni, passavano a Close (livello 4).

Le panoramiche di riferimento non usavano alcuna inquadratura. Mostrano l'intera finestra con etichette numerate, perché lo scopo è nominare ogni area. Step Numbers è uno strumento Pro, quindi nel piano gratuito lo stesso risultato richiede etichette Text posizionate a mano.

Decidi quando non acquisire

Ogni immagine è un futuro aggiornamento, quindi la politica deve elencare anche i casi in cui non serve alcuno screenshot. Il team dell'esempio ha saltato le immagini dei passaggi in cui l'unica azione era digitare un valore in un campo con etichetta. Ha inoltre saltato le notifiche di conferma che scompaiono dopo 3 secondi, descrivendo il messaggio nel testo.

Se nessuno dei cinque punti si applica, scrivi il passaggio solo come testo. Nell'esempio, questa regola ha eliminato 38 delle 217 immagini pianificate per le guide operative prima dell'inizio delle acquisizioni.

Prepara un account di esempio per ogni acquisizione

Gli screenshot tratti da account diversi mostrano nomi, totali e date diversi, e i lettori se ne accorgono. Il team dell'esempio ha creato un unico workspace di esempio con 3 clienti, 12 fatture e 2 metodi di pagamento, tutti con nomi segnaposto. Ogni guida parte da quel workspace, così lo stesso nome cliente compare in tutte le pagine.

Ripristina i dati di esempio prima di ogni esecuzione. Una guida registrata dopo che un'altra guida ha eliminato una fattura mostrerà 11 fatture invece di 12, e il successivo aggiornamento non corrisponderà. Scrivi i passaggi di ripristino in cima al documento della politica, così un altro autore può ripeterli.

Imposta la finestra del browser a una dimensione precisa prima di ogni esecuzione e lasciala invariata. Temposhot acquisisce la finestra alla sua dimensione attuale e non ridimensiona le finestre. Una nota nella politica, ad esempio "finestra del browser larga 1440 punti, zoom al 100 percento", mantiene le acquisizioni fatte in giorni diversi alla stessa scala.

Assegna nomi e conserva le immagini per la sostituzione

Ogni immagine verrà sostituita prima o poi. Assegna nomi ai file in modo da trovare rapidamente tutte le immagini di una stessa schermata.

Un modello come area-task-step.png, ad esempio billing-change-plan-03.png, ordina i file per area e attività. Mantieni una cartella per ogni guida e conserva il Document di Temposhot di ciascuna guida, così puoi esportarlo di nuovo dopo le modifiche.

Gli export delle immagini di Temposhot usano i titoli delle pagine nei nomi dei file. Imposta i titoli prima dell'export oppure rinomina i file nel repository della documentazione in un secondo momento. Il pacchetto ZIP aggiunge document.json accanto alle pagine PNG renderizzate, utile se importi i file in un sistema di documentazione tramite script.

Struttura delle cartelle per il set di esempio

Una cartella per ogni area di prodotto contiene una cartella per ogni guida. Le immagini esportate si trovano accanto alla pagina che le usa, quindi una pull request che modifica una guida mostra anche quali immagini sono cambiate.

Mantieni allineati titoli delle pagine e nomi dei file

Poiché Temposhot assegna ai file immagine il nome della pagina, un titolo come Click "Change plan" produce un nome file difficile da ordinare. Esistono due modi praticabili. Riscrivi i titoli con il testo definitivo rivolto al lettore e rinomina i file nel repository con uno script, oppure esporta un pacchetto ZIP e usa l'ordine delle pagine in document.json per assegnare i nomi.

Qualunque strada scelga il team, il numero del passaggio nel nome del file deve corrispondere al numero del passaggio nella pagina. Quando il passaggio 4 viene eliminato, rinumera i file successivi nello stesso commit.

Conserva i Document di origine

Ogni immagine esportata deriva da un Document sul Mac che l'ha registrata. I Document si trovano nella libreria Documents (Command+4) di quel Mac, e Temposhot non li sincronizza. Assegna a ogni Document lo stesso nome della cartella della guida, ad esempio billing-change-plan, così l'origine di ogni immagine si trova cercando nella libreria.

Crea prima le guide operative, poi i tour generali

Le guide operative rispondono alle domande più comuni e sono le più facili da verificare. Scrivile per prime.

1. Apri Action Capture

   Premi Command+3, seleziona Start Action Capture e scegli Specific Window.

2. Esegui l'attività

   Completa l'attività una volta cliccando nei passaggi. Ogni clic accettato salva la finestra subito prima del clic, con un titolo provvisorio generato da Parse clicked elements.

3. Termina e modifica

   Seleziona Finish capture. Nell'editor, riscrivi i titoli, imposta l'inquadratura delle pagine e aggiungi i segni.

4. Esporta le pagine

   Apri More export formats e scegli le pagine PNG o WebP per il sito di documentazione.

I tour di prodotto e le pagine di panoramica vengono dopo, quando le guide operative hanno mostrato quali schermate contano di più. La guida ad Action Capture e la guida all'export dei Document descrivono i dettagli.

Ordina il primo lotto per volume di ticket

Il team dell'esempio ha acquisito le nove domande più frequenti nella prima settimana. Ogni guida ha richiesto circa 25 minuti: 5 minuti per ripristinare l'account di esempio, 5 minuti per registrare e 15 minuti per modificare titoli, inquadratura e segni. Nove guide hanno richiesto complessivamente circa quattro ore.

Riscrivi i titoli provvisori in istruzioni

Parse clicked elements compila il titolo di ogni pagina con il nome del controllo, ad esempio Click "Change plan". I clic su controlli senza un nome leggibile ricevono il titolo Click here. Entrambi sono provvisori. Un titolo rivolto al lettore inizia con un verbo, indica il controllo in grassetto e aggiunge il risultato quando non è ovvio.

Titolo provvisorio	Titolo riscritto
Click "Billing"	Apri Billing nella barra laterale
Click here	Seleziona la scheda del piano Team
Click "Confirm"	Seleziona Confirm per cambiare piano al prossimo rinnovo

Il titolo riscritto diventa anche il nome del file immagine al momento dell'export, quindi un titolo chiaro aiuta sia i lettori sia il repository.

Verifica il numero di passaggi rispetto al limite gratuito

Il piano gratuito interrompe un'esecuzione di Action Capture dopo 5 passaggi, e i passaggi già acquisiti restano salvati. Le guide da sette passaggi come quelle dell'esempio richiedono Temposhot Pro, oppure due esecuzioni aggiunte a un unico Document. Per aggiungere una seconda esecuzione, usa Capture new images… nel pannello Pages: i nuovi fotogrammi vengono aggiunti al Document aperto.

Modifica le pagine con le scorciatoie da tastiera

La modifica occupa gran parte dei 25 minuti previsti per ogni guida. Le scorciatoie dell'editor qui sotto coprono le modifiche più frequenti nelle pagine di documentazione.

Le annotazioni non sono distruttive. Un rettangolo aggiunto in questa release può essere spostato o eliminato dopo il prossimo redesign senza acquisire di nuovo il passaggio, purché la schermata sottostante corrisponda ancora.

Collega il set di documentazione

I lettori raramente atterrano sulla pagina che cercano. Collega le pagine in modo che possano passare da un concetto all'attività e da un errore alla correzione.

• Ogni guida operativa rimanda ai prerequisiti e all'attività successiva più probabile.
• Ogni pagina di risoluzione dei problemi rimanda alla guida operativa che risolve il problema.
• Ogni pagina di riferimento rimanda alle attività che usano quella schermata.

Una breve pagina indice per ogni area di prodotto, con le attività raggruppate per obiettivo, aiuta i lettori che sfogliano invece di cercare.

Schema dei collegamenti a partire da una domanda

La domanda "Perché il mio export è vuoto" nell'esempio ha generato una catena di quattro pagine. Un lettore che atterra su una qualunque di esse può raggiungere le altre tre con un solo clic.

Evita le pagine orfane

Dopo la pubblicazione, elenca tutte le pagine e conta i collegamenti in entrata. Una pagina senza collegamenti in entrata è raggiungibile solo tramite la ricerca. Nell'esempio, 4 delle 52 pagine non ne avevano, e ciascuna è stata aggiunta all'indice della propria area.

Assegna responsabilità e condizioni di revisione

Assegna a ogni pagina un responsabile, di solito il team che gestisce la funzionalità. Registra la versione del prodotto a cui corrispondono gli screenshot.

Le condizioni di revisione funzionano meglio dei soli promemoria di calendario:

• Un rilascio modifica una schermata presente nel set.
• Un'etichetta o una voce di menu viene rinominata.
• Il supporto segnala un passaggio che non corrisponde più.
• Passa un intervallo fisso, ad esempio un trimestre, senza altre condizioni.

L'articolo su come mantenere aggiornata la documentazione con screenshot descrive la routine di aggiornamento.

Sostituisci le immagini dopo un rilascio

Quando un rilascio modifica una schermata, i nomi dei file rendono facile trovare le immagini interessate. Cerca nel repository il prefisso dell'area, apri i Document corrispondenti e ripeti solo i passaggi modificati.

Le nuove pagine create da un'acquisizione possono essere inserite dopo la pagina selezionata. Seleziona la pagina che precede il passaggio modificato, esegui l'acquisizione e la nuova pagina viene collocata nella posizione corretta.

Ripartisci la responsabilità per area di prodotto

Un solo autore non può revisionare 52 pagine a ogni rilascio. Il team dell'esempio ha assegnato ogni area all'ingegnere che la gestisce, con l'autore come redattore. Il responsabile segnala le schermate modificate nel ticket di rilascio, e l'autore sostituisce le immagini.

Registra la versione del prodotto su ogni pagina

Aggiungi la versione del prodotto nei metadati della pagina o nell'ultima riga, ad esempio "Gli screenshot corrispondono alla versione 4.2". Quando il supporto segnala una mancata corrispondenza, la versione indica al responsabile quanto la pagina è indietro. Le pagine più indietro di due release passano in cima alla coda di revisione.

Domande frequenti

Quanti screenshot deve avere una pagina di documentazione software?

Uno per passaggio nelle guide operative, e il minor numero possibile altrove. Ogni immagine è un futuro aggiornamento, quindi aggiungine una solo quando riduce lo sforzo del lettore.

Gli screenshot della documentazione devono mostrare l'intero schermo?

Raramente. Ritaglia la finestra o il pannello. Le immagini a schermo intero mostrano app non correlate e rendono piccolo il testo dell'interfaccia.

Che cos'è la documentazione visiva?

È la documentazione che usa screenshot, diagrammi o video insieme al testo. Vedi documentazione visiva nel glossario.

Quale formato immagine conviene usare su un sito di documentazione?

Le pagine PNG mantengono nitido il testo dell'interfaccia. Le pagine WebP producono file più leggeri e compaiono in More export formats solo quando sul Mac è disponibile un encoder WebP. Il Image Compressor può ridurre ulteriormente i file PNG prima del caricamento.

Quanto tempo richiede aggiornare gli screenshot dopo un redesign?

Dipende da quante immagini mostrano le schermate modificate. Nell'esempio, il redesign di un'area ha interessato circa 50 delle 247 immagini. Rieseguire solo i passaggi modificati dai Document salvati ha richiesto da uno a due giorni, contro circa una settimana per ricostruire le stesse guide da zero.

Più autori possono condividere un unico Document di Temposhot?

No. I Document sono memorizzati sul Mac che li ha creati. Condividi i file esportati tramite il repository della documentazione e conserva il Document di origine di ogni guida sul Mac del suo responsabile.

Trasforma i tuoi clic in una guida passo passo chiara

Action Capture registra ogni guida operativa in un unico passaggio, con dimensione della finestra costante e titoli provvisori. Scarica Temposhot e inizia dalla domanda più frequente della tua lista.