Come mantenere aggiornata la documentazione con screenshot

La documentazione con screenshot diventa obsoleta una release alla volta. Un pulsante rinominato, un menu spostato o un nuovo tema fanno sembrare sbagliata una guida anche quando i passaggi funzionano ancora, e i lettori smettono di fidarsi.

Questo articolo descrive una procedura di manutenzione: chi è responsabile di ogni guida, quali eventi attivano una revisione e come sostituire solo le pagine modificate usando Temposhot su Mac.

La procedura è illustrata con un unico esempio svolto. Una guida per amministratori di 40 pagine descrive un prodotto web che rilascia una versione ogni 6 settimane. La versione 4.3 rinomina un pulsante, aggiunge un campo a una finestra di dialogo e sposta una voce della barra laterale, quindi la guida deve essere allineata prima del giorno del rilascio.

Assegna un responsabile e una versione verificata

Ogni guida deve avere un unico responsabile con nome. Di solito è la persona o il team che gestisce la funzione mostrata nella guida. La responsabilità condivisa spesso significa che nessuno la aggiorna.

Registra nella copertina o nella prima pagina:

• Responsabile: nome di una persona o di un team.
• Versione verificata: la versione del prodotto o la data di rilascio a cui corrispondono gli screenshot.
• Ultima verifica: la data in cui qualcuno ha seguito la guida dall'inizio alla fine.

"Verificata" significa che qualcuno ha eseguito l'attività seguendo la guida, non che qualcuno l'abbia solo guardata.

Metti il registro dove lo vedono i lettori

La versione verificata deve comparire nella guida stessa, non solo in un foglio di tracciamento. Un lettore con la versione 4.1 che apre una guida marcata 4.3 capisce subito perché una schermata è diversa. Il personale di supporto può chiedere la versione prima di analizzare una discrepanza.

In Temposhot, la prima pagina del Document può riportare il registro nei campi Page title e Description. Un export PDF con Cover page attivo inizia con il titolo del documento e il numero di passaggi, quindi un titolo come "Guida amministratori, verificata sulla 4.3" mostra la versione in copertina. La modifica delle impostazioni della copertina fa parte della personalizzazione PDF, che richiede Temposhot Pro. Le impostazioni predefinite includono già la pagina di copertina.

Dividi una guida lunga per responsabile

La guida per amministratori di 40 pagine dell'esempio copre membri, ruoli, fatturazione e registri di audit. Quattro aree corrispondono di solito a quattro responsabili. Un responsabile per sezione funziona meglio di un unico responsabile per 40 pagine, perché il team della fatturazione nota per primo le modifiche alla fatturazione.

Un responsabile di sezione approva solo le proprie pagine. Il responsabile della guida raccoglie le approvazioni e aggiorna la versione verificata quando sono arrivate tutte e quattro.

Usa le modifiche al prodotto come criteri di revisione

Le revisioni basate solo sul calendario intercettano i problemi in ritardo. Collega le revisioni agli eventi che modificano le schermate:

Trigger	Chi se ne accorge	Azione
Le note di rilascio citano una schermata presente in una guida	Responsabile della documentazione	Controlla le guide interessate prima del rilascio
Un'etichetta o una voce di menu viene rinominata	Prodotto o design	Cerca nelle guide l'etichetta precedente
Redesign del tema o del layout	Design	Pianifica una riacquisizione completa
Il supporto segnala una discrepanza	Supporto	Risolvi entro il giorno lavorativo successivo
Nessun trigger per un trimestre	Responsabile della documentazione	Verifica a campione le guide più usate

Chiedi al team di prodotto di etichettare le voci di rilascio che modificano l'interfaccia visibile. Questa sola abitudine rende automatica la maggior parte dei trigger.

Inserisci la revisione in un ciclo di rilascio di 6 settimane

Con un rilascio ogni 6 settimane, il lavoro sulla documentazione ha uno slot fisso. L'interfaccia viene congelata su una build di staging alcuni giorni prima del rilascio, e gli screenshot acquisiti in precedenza possono ancora cambiare. Acquisire sulla build congelata ed esportare prima del giorno del rilascio mantiene allineati guida e prodotto.

Acquisire troppo presto è l'errore più comune in questo ciclo. Se un'etichetta cambia di nuovo dopo il congelamento, le stesse pagine vanno riacquisite una seconda volta.

Usa un account di staging con dati stabili

Riacquisisci su un account i cui dati non cambiano tra un rilascio e l'altro. Gli stessi tre membri di test, gli stessi numeri di fattura e lo stesso nome del piano mantengono i nuovi screenshot coerenti con le pagine rimaste invariate. Una pagina acquisita con dati di esempio diversi risulta fuori posto accanto a quelle vecchie, anche se l'interfaccia è identica.

Gestisci una discrepanza segnalata dal supporto

Il supporto trova spesso le modifiche che le note di rilascio non riportavano. Un ticket che dice "la guida mostra un pulsante che non riesco a trovare" richiede tre informazioni prima di qualsiasi riacquisizione: il nome della guida, il numero di pagina e la versione del prodotto usata dal cliente. Senza la versione, un cliente con la 4.1 può far aggiornare una guida già corretta per la 4.3.

Fornisci al team di supporto un breve modello con questi tre campi. Una discrepanza confermata sulla versione corrente va nel giorno lavorativo successivo. Una discrepanza su una versione più vecchia va invece alla questione dell'archivio descritta più avanti.

Associa la modifica ai passaggi interessati

Prima di riacquisire, individua esattamente quali pagine mostrano la schermata modificata. Un inventario rende il lavoro rapido:

Guida	Schermate mostrate	Versione verificata	Responsabile
Invita un membro del team	Membri, finestra di invito	4.2	Admin del team
Esporta le fatture	Fatturazione, elenco fatture	4.1	Finanza

Quando una release modifica la finestra di invito, l'inventario indica la guida e le pagine da controllare. Senza inventario, qualcuno deve aprire ogni guida.

Esempio svolto: release 4.3

La release 4.3 introduce tre modifiche visibili. Il pulsante Add member nella pagina Members viene rinominato Invite. La finestra di invito riceve un nuovo campo Role. La voce Invoices passa dal menu dell'account alla barra laterale di Billing.

L'inventario associa queste modifiche a 7 pagine su 40:

Modifica nella 4.3	Pagine che la mostrano	Metodo di riacquisizione
Add member rinominato in Invite	6 (elenco dei membri), 14 (schermata di riepilogo)	Action Capture della pagina Members
Campo Role nella finestra di invito	7, 8, 9 (finestra di invito, scelta del ruolo, conferma)	Action Capture del flusso di invito
Invoices spostato nella barra laterale di Billing	27, 28 (navigazione ed elenco delle fatture)	Action Capture del percorso di fatturazione

Le altre 33 pagine restano invariate. I loro screenshot corrispondono ancora alla 4.3, quindi riacquisirle aggiungerebbe lavoro senza cambiare ciò che vedono i lettori.

Trova differenze visive con Compare Images

Le note di rilascio non elencano ogni modifica al pixel. Una variazione di spaziatura, una nuova icona o un pulsante ricolorato possono sfuggire. Per le pagine che le note di rilascio non citano, acquisisci uno screenshot nuovo della stessa schermata e confrontalo con l'immagine della pagina esportata.

Compare Images mostra due versioni con un cursore, una dissolvenza, affiancate o come vista delle differenze in pixel. La vista delle differenze evidenzia le aree modificate, e questo rende facile notare un controllo spostato. Lo strumento funziona nel browser ed è un controllo rapido delle 33 pagine che l'inventario ha segnato come invariate.

Sostituisci solo i passaggi interessati

Riacquisire un'intera guida per una sola finestra modificata fa perdere tempo e aumenta il rischio di nuovi errori. Sostituisci solo le pagine che sono cambiate.

1. Apri il Document

   Premi Command+4 e apri il Document della guida.

2. Acquisisci le nuove schermate

   Apri il menu di aggiunta nel pannello Pages, scegli Capture new images…, poi Action Capture. Esegui solo i passaggi modificati e seleziona Finish capture. Le nuove pagine tornano nell'editor e possono essere inserite dopo la pagina corrente.

3. Sposta e rimuovi

   Trascina le nuove pagine nella posizione corretta nel pannello Pages, oppure usa Move up e Move down. Usa Delete page per le pagine obsolete.

4. Riporta titoli e segni

   Copia titoli e descrizioni dalle vecchie pagine prima di eliminarle. Copia le annotazioni con Command+C e Command+V, poi correggi la loro posizione.

5. Esporta di nuovo

   Seleziona Export PDF oppure usa More export formats. Le esportazioni riflettono l'ordine attuale delle pagine, l'inquadratura e le annotazioni.

La guida a pagine e importazioni descrive come aggiungere pagine da acquisizioni, immagini e Capture History.

Ripeti Action Capture o aggiungi da Capture History

Esistono due modi per inserire nuove pagine nel Document. Capture new images… avvia un'acquisizione dall'interno del Document e aggiunge i fotogrammi al termine dell'esecuzione. Add from Capture History… importa fotogrammi da una sessione già esistente, per esempio un'esecuzione fatta da un collega sul Mac di staging.

Nell'esempio, il flusso di invito viene riacquisito direttamente. Il percorso di fatturazione era già stato acquisito sullo staging il giorno prima, quindi i suoi 2 fotogrammi arrivano da Add from Capture History…. Il selettore consente di espandere quella sessione e spuntare solo i 2 fotogrammi necessari.

Procedura per riacquisire il flusso di invito

Il flusso di invito è composto da 5 clic: Invite, il campo email, il menu Role, l'opzione Admin e Send invite. Cinque passaggi rientrano nel limite di Action Capture del piano gratuito, pari a 5 passaggi per esecuzione. Un percorso più lungo richiederebbe Temposhot Pro oppure la suddivisione in due esecuzioni.

Usa lo stesso tipo di destinazione e lo stesso stile di marcatore dell'esecuzione originale. Una guida in cui le pagine da 6 a 9 usano un marcatore circolare e le altre un rettangolo sembra rattoppata, anche quando ogni passaggio è corretto.

Mantieni la stessa dimensione della finestra

La destinazione Specific Window acquisisce la finestra alla sua dimensione attuale. Se la finestra del browser era larga 1440 pixel per le pagine originali, ridimensionala alla stessa larghezza prima della riacquisizione. Una larghezza diversa cambia l'impaginazione e le dimensioni del testo accanto alle 33 pagine invariate.

Screenshot Resolution Checker mostra la dimensione in pixel di un'immagine di pagina esportata. Controlla una vecchia pagina e una nuova: le larghezze devono coincidere.

Ricontrolla testi, annotazioni e privacy

Le nuove schermate spesso alterano ciò che le circonda:

• Titoli che citano un'etichetta vecchia: "Select Add member" quando il pulsante ora dice Invite.
• Frecce e marcatori che ora puntano a uno spazio vuoto.
• Un'inquadratura che taglia un controllo spostato.
• Nuove schermate che mostrano dati che quelle vecchie non mostravano, come una nuova barra laterale con dei nomi.

Riapplica Focus on action alle pagine Action Capture, oppure Custom alle altre. Oscura i nuovi dati personali con Blur (B, Pro).

Cerca l'etichetta precedente in ogni pagina

Un controllo rinominato compare di solito in più punti rispetto alle pagine che lo mostrano. Nell'esempio, "Add member" compare nei titoli delle pagine 6 e 14, ma anche nella descrizione della pagina 3, che spiega dove trovare la pagina Members. Leggi Page title e Description di ogni pagina nel Page Inspector ed elenca ogni punto in cui compare l'etichetta precedente. Correggili tutti nella stessa modifica.

Allinea l'inquadratura delle pagine vicine

Le pagine Action Capture supportano cinque livelli di inquadratura: Wide, Relaxed, Balanced, Close e Tight. Se le pagine 5 e 10 usano Balanced, imposta anche le pagine da 6 a 9 su Balanced. Livelli misti fanno saltare lo zoom da una pagina all'altra, e questo sembra un errore.

Premi F per aprire l'editor dell'inquadratura su una pagina. Reset to action ricostruisce l'inquadratura automatica attorno al punto di clic se un ritaglio manuale è sbagliato.

Testa la guida completa

Segui l'intera guida sulla versione corrente, dalla prima pagina al risultato, usando un account di test. Una pagina sostituita può interrompere comunque il flusso, per esempio quando la modifica ha spostato anche il passaggio successivo.

Aggiorna i campi Verified version e Last verified solo dopo che questo test è stato superato.

Cosa ha rilevato il test nell'esempio

Nell'esempio della 4.3, il test end-to-end ha individuato un problema che la revisione delle pagine non aveva rilevato. La pagina 10 diceva ancora ai lettori di "close the dialog" dopo l'invio dell'invito, ma la 4.3 la chiude automaticamente. Lo screenshot della pagina 10 era ancora corretto, quindi né l'inventario né Compare Images lo hanno segnalato. Lo ha rilevato solo seguire i passaggi.

Correggi la descrizione, poi ripeti il test dalla pagina 5. Un nuovo test parziale a partire dalla pagina precedente la prima modifica è sufficiente quando il resto della guida non è cambiato.

Scegli chi esegue il test

Chi ha riacquisito le pagine è il tester peggiore, perché conosce già la posizione di ogni controllo. Un responsabile di sezione o un collega del supporto che non ha partecipato legge la guida come farebbe un cliente. Nell'esempio, il responsabile del team di sicurezza ha testato la sezione membri e ha trovato il problema della pagina 10 in circa 10 minuti.

Consegna al tester il PDF esportato, non il Document nell'editor. Il test copre così il file che ricevono i lettori, incluso l'ordine delle pagine, la pagina di copertina e la qualità delle immagini.

Ripeti il test dopo gli hotfix

Un hotfix tra due release può modificare un'etichetta senza una nota di rilascio. Se il supporto segnala una discrepanza nel ciclo di 6 settimane, ripeti la stessa associazione: trova le pagine nell'inventario, sostituiscile ed esegui un test parziale a partire dalla pagina precedente la modifica. Aggiungi la versione dell'hotfix al campo Verified version, per esempio 4.3.1.

Archivia solo quando i lettori hanno bisogno dello storico

La maggior parte dei lettori vuole solo la guida corrente. Conserva le versioni precedenti quando qualcuno usa ancora una versione vecchia del prodotto, per esempio clienti su una release a lungo termine, oppure quando una normativa richiede una registrazione.

Quando archivi, indica chiaramente nel nome e nella copertina che il file è archiviato, per esempio invite-teammate_v4.1_archived.pdf. Documenti e Capture History sono archiviati localmente sul Mac, quindi conserva i file esportati nello spazio di archiviazione condiviso invece di affidarti al Mac. Eliminare il lavoro di Action Capture può rimuovere anche il suo Document, quindi conserva il Document di origine finché la guida non viene ritirata.

Una struttura di cartelle per le esportazioni

Una struttura di cartelle fissa rende facile trovare il file corrente. Imposta il percorso di esportazione in Settings > General sulla cartella di lavoro della guida, poi sposta nella posizione finale i file completati.

Solo la cartella current è collegata dal centro assistenza o dalla intranet. I file archiviati restano raggiungibili per i clienti con versioni vecchie, ma nessuno ci arriva per errore.

Controlla la conservazione di Capture History

Capture History conserva 30 sessioni per impostazione predefinita, con un limite che può essere impostato da 1 a 500 in Settings > History. Un team che riacquisisce ogni 6 settimane più guide può raggiungere 30 sessioni in pochi cicli. Il Document conserva copie proprie di ogni immagine, quindi eliminare le sessioni vecchie non danneggia la guida, ma i fotogrammi grezzi per riutilizzi futuri vanno persi.

Tieni traccia della manutenzione con questo registro

Conserva una riga per guida in un foglio di calcolo o nello strumento di documentazione:

• Nome della guida e posizione del file.
• Responsabile.
• Schermate mostrate.
• Versione verificata e data dell'ultima verifica.
• Problemi aperti segnalati dal supporto o dai lettori.
• Prossima verifica a campione programmata.

Una breve revisione settimanale di questo elenco individua le modifiche quando sono ancora piccole. Una pulizia annuale le individua quando i lettori le hanno già incontrate.

Esempio di registro dopo la release 4.3

Campo	Valore
Guida	Guida amministratori, current/admin-guide_v4.3.pdf
Responsabile	Responsabile della documentazione, con quattro responsabili di sezione
Schermate mostrate	Members, finestra di invito, Roles, Billing, Invoices, Audit log
Versione verificata	4.3, ultima verifica il giorno del rilascio
Problemi aperti	Nessuno
Prossima verifica a campione	Release 4.4, 6 settimane dopo

Abitudini che fanno durare più a lungo gli screenshot

Alcuni screenshot si rompono a ogni rilascio, altri restano validi per anni. La differenza dipende soprattutto da quanto sono stretti i ritagli e da quali dati mostrano.

Domande frequenti

Con quale frequenza va rivista la documentazione con screenshot?

Dopo ogni release che modifica una schermata mostrata, più una verifica a campione a intervalli fissi, per esempio una volta al trimestre, per le guide senza altri trigger.

Come ridurre la frequenza con cui gli screenshot si rompono?

Ritaglia strettamente il pannello rilevante con Framing, evita date e nomi negli screenshot e indica i controlli nel testo, così il lettore può seguire la guida anche quando cambia una modifica minore dello stile.

Bisogna riacquisire l'intera guida dopo un redesign?

Per un cambiamento completo di layout o di tema, sì. Per un pulsante rinominato o un controllo spostato, sostituisci solo le pagine interessate.

Riesportare il Document sovrascrive il vecchio PDF?

No. Se nel percorso di esportazione esiste già un file con lo stesso nome, Temposhot aggiunge un numero al nuovo nome del file. Sposta o rinomina prima il vecchio file, oppure sostituisci a mano la copia pubblicata.

Posso aggiornare le pagine di una guida creata da screenshot manuali?

Sì. Usa Upload images… per aggiungere nuovi file immagine, oppure Capture new images… per acquisirli. Il Document tratta ogni pagina allo stesso modo, indipendentemente dall'origine; solo le pagine Action Capture hanno un punto di clic per Focus on action.

Quanto richiede un aggiornamento parziale rispetto a una riacquisizione completa?

Nella guida di 40 pagine dell'esempio, sostituire 7 pagine e ricontrollarle ha richiesto circa 35 minuti. Una riacquisizione completa richiederebbe anche di riscrivere o controllare 40 titoli e descrizioni e di riapplicare le annotazioni su ogni pagina, quindi richiede diverse volte più tempo.

Trasforma i tuoi clic in una guida passo passo chiara

Action Capture riacquisisce solo i passaggi modificati e li aggiunge al Document esistente. Scarica Temposhot e aggiorna prima la guida con la versione verificata più vecchia.