Come dettare una segnalazione di bug che altri possano riprodurre

"Si è rotto di nuovo" è una segnalazione sincera. Ma è anche difficile da risolvere. Quando apri il sistema di tracciamento delle segnalazioni, la schermata, il pulsante e il risultato esatti si sono già confusi nella memoria. Dettare una segnalazione di bug può conservare questi dettagli finché sono freschi, ma solo se dai una struttura al discorso prima di iniziare.

Questo è un breve metodo per trasformare un problema osservato in una segnalazione che un’altra persona possa riprodurre. Funziona sia che tu stia testando un progetto personale, aprendo una segnalazione al lavoro o contribuendo alla manutenzione di uno strumento open source. Dovrai comunque digitare i comandi esatti e controllare la segnalazione finale. La voce serve a raccontare ciò che è successo, non a inventare prove.

Parti dal problema, non dalla diagnosi

Una segnalazione di bug prende una brutta piega quando il titolo presenta una teoria: "La cache del database è guasta." Potresti avere ragione, ma chi indaga ha bisogno prima di tutto di ciò che hai osservato. Un titolo migliore indica l’azione e il risultato: "Salvare una bozza cancella la lingua selezionata nelle Impostazioni." Questo si può verificare senza accettare la tua ipotesi sulla causa.

La stessa regola aiuta quando detti. Dedica una frase all’attività che cercavi di completare e un’altra a ciò che il software ha fatto invece. Non cominciare con un lungo resoconto della settimana o con un’ipotesi sul sottosistema guasto. Se il problema si verifica a intermittenza, dillo. Se si verifica ogni volta sul tuo computer, dillo pure, ma non sostenere che succeda a tutti.

La guida alla creazione di una segnalazione di GitHub spiega come inserire un titolo e un testo descrittivi e osserva che un repository può fornire un modello di segnalazione. Usa quel modello quando è disponibile. La struttura da dettare qui sotto ti aiuta a raccogliere i fatti prima di compilare i campi; non è un motivo per ignorare le istruzioni del progetto.

La nota vocale in cinque campi

Apri una bozza privata vuota invece di pubblicare direttamente su un sistema di tracciamento aperto a tutti. Posiziona il cursore nell’editor e detta cinque brevi campi. Vai a capo tra un campo e l’altro. La prima stesura dovrebbe sembrare la testimonianza di chi ha visto il problema, non una nota di rilascio rifinita:

1. Contesto: Cosa stavi cercando di fare? Indica la pagina, la funzione o l’operazione.
2. Passaggi: Quali azioni hanno prodotto il problema? Numerale in ordine.
3. Atteso: Quale risultato ti aspettavi ragionevolmente?
4. Effettivo: Cosa è successo sullo schermo? Cita un breve messaggio di errore solo dopo averlo verificato.
5. Ambito: Quando è successo, in quale ambiente e riesci a ripeterlo?

Ecco un modello da copiare e incollare. Sostituisci ogni elemento tra parentesi quadre con un dettaglio osservato. Se non conosci un campo, scrivi "non verificato" invece di riempirlo con una risposta plausibile.

Titolo: [azione] causa [risultato osservato]
Contesto: Stavo cercando di [obiettivo] in [funzione/pagina].
Passaggi per riprodurre il problema:
1. [stato iniziale esatto]
2. [prima azione]
3. [azione successiva]
Atteso: [cosa sarebbe dovuto accadere]
Effettivo: [cosa è successo, incluso il testo di errore verificato]
Frequenza: [una volta / a volte / a ogni tentativo su questo dispositivo]
Ambiente: [versione dell’app, sistema operativo, browser se pertinente]
Prove: [schermata sicura o registro da cui sono stati rimossi i dati sensibili, se utile]

Non leggere ad alta voce le parentesi quadre aspettandoti che diventino una struttura formattata. Inserisci prima le intestazioni nell’editor, poi detta il contenuto di ciascun campo. Se usi una tastiera vocale per computer come Talkpad su macOS o Windows, posiziona il cursore nella bozza privata e detta un campo alla volta. Così sarà più facile fermarti, controllare e correggere ogni parte prima di pubblicare.

Riproduci il problema una volta, poi descrivi i clic

La memoria trasforma una sequenza in un riassunto. "Ho cambiato un’impostazione e la pagina si è bloccata" potrebbe tralasciare l’aggiornamento della pagina, il cambio di account o il modulo non salvato. Ripeti la sequenza se è sicuro farlo, con la bozza aperta accanto all’app interessata. Fermati dopo ogni azione e annota ciò che hai fatto. Non provocare ripetutamente un bug che cancella dati o addebita denaro solo per migliorare la formulazione.

Mantieni i passaggi letterali: "Apri Impostazioni, scegli Spagnolo, fai clic su Salva, riapri Impostazioni." Evita "vai nelle solite preferenze e fai quella cosa." Se l’app ha diversi pulsanti Salva, indica il pannello. Se il bug compare solo dopo aver ricaricato la pagina, includi quel passaggio. Un collega che non ha mai visto il tuo schermo dovrebbe poter seguire i passaggi senza scriverti per chiederti quale clic manca.

Puoi dettare il racconto, ma usa la tastiera per le stringhe delicate. Un sistema di riconoscimento potrebbe trasformare il nome di un pacchetto in parole comuni, cambiare le maiuscole in un’opzione a riga di comando o eliminare un segno meno. Incolla dall’app una traccia dello stack o un errore verificati invece di pronunciarli. Lo stesso vale per una versione precisa come 1.4.12. Consulta la nostra guida ai nomi e ai termini tecnici per parole meno rischiose che richiedono comunque un’attenta revisione.

Distingui il risultato atteso da quello effettivo

È qui che una segnalazione diventa utile. "Il modulo non ha funzionato" non dice quasi nulla a chi indaga. "Dopo aver fatto clic su Salva, è comparsa la conferma, ma riaprendo Impostazioni la lingua era tornata all’inglese" descrive una differenza osservabile. Il risultato atteso può essere altrettanto semplice: "Quando riapro Impostazioni, la lingua salvata dovrebbe essere ancora lo spagnolo."

Non infilare una proposta di correzione nel campo del risultato atteso. "L’app dovrebbe usare una cache diversa" è un suggerimento di implementazione, non un’aspettativa visibile all’utente. Metti le eventuali ipotesi in una nota chiaramente contrassegnata alla fine, senza nascondere l’incertezza. Il tuo collega potrebbe scoprire che la causa è una risposta API, un client con dati obsoleti o qualcos’altro.

Quando il riconoscimento vocale sbaglia una negazione, la segnalazione può assumere il significato opposto. Confronta "la finestra di dialogo non si è chiusa" con "la finestra di dialogo si è chiusa." Rileggi queste frasi sullo schermo prima di pubblicare. Il nostro metodo di revisione che dà priorità ai rischi mette negazioni, numeri e nomi prima dei ritocchi stilistici proprio per questo.

Aggiungi l’ambiente senza creare un dossier investigativo

Le informazioni minime utili sull’ambiente sono di solito la versione dell’app, il sistema operativo, il browser se il bug si verifica nel browser e le impostazioni necessarie per riprodurlo. Indica se riesci a riprodurlo in una sessione pulita o su un altro dispositivo solo se hai fatto davvero la prova. Un orario o una condizione di rete conta quando cambia l’esito; altrimenti aggiunge rumore.

Controlla una schermata prima di allegarla. Nomi utente, indirizzi email, token, dati dei clienti e anteprime delle chat possono nascondersi negli angoli. Ritaglia l’area pertinente o sfoca i dettagli sensibili con un editor affidabile. Anche i registri richiedono la stessa verifica. Se il sistema di tracciamento è pubblico, considera pubblici anche gli allegati. Per le questioni legate alle regole aziendali, consulta la nostra lista di controllo sulla privacy della digitazione vocale prima di dettare materiale riservato in qualsiasi strumento.

Talkpad può inserire una bozza dettata nell’app in cui si trova il cursore, ma non verifica se una schermata è sicura o se una traccia dello stack è corretta. Questi controlli spettano a te. Se le regole aziendali limitano l’elaborazione vocale dei dati relativi agli incidenti, rispettale e digita manualmente le parti sensibili.

Due passaggi di revisione prima di pubblicare

Il primo passaggio riguarda la riproducibilità. Parti dallo stato indicato e segui letteralmente i passaggi. Il problema si presenta? I risultati atteso ed effettivo sono diversi e comprensibili? Hai omesso un accesso o un’impostazione che cambia l’esito? Se non riesci a riprodurre di nuovo il problema, modifica il campo della frequenza per rifletterlo invece di nascondere l’incertezza.

Il secondo passaggio riguarda i rischi. Confronta le stringhe di versione e i messaggi di errore con le rispettive fonti. Rimuovi le informazioni riservate dal testo e dagli allegati. Sostituisci le supposizioni con fatti osservabili, oppure presentale come ipotesi. Accorcia l’introduzione se ritarda l’arrivo ai passaggi. Puoi usare il kit di strumenti per rivedere le bozze dettate quando la prima stesura arriva come un blocco di parlato invece che come campi ordinati.

Una segnalazione utile non deve essere lunga. Alcuni bug richiedono tre passaggi e due frasi; altri hanno bisogno di un esempio controllato. Evita di allungare il testo inutilmente. L’obiettivo è consentire a un’altra persona di riprodurre il comportamento e capire perché ti aspettavi qualcosa di diverso. Se non sai spiegare lo stato iniziale, indaga ancora un po’ prima di pubblicare.

Domande frequenti

Posso usare la dettatura per scrivere una segnalazione di bug?

Sì. Detta il contesto, i passaggi per riprodurre il problema e il comportamento atteso rispetto a quello effettivo in una bozza privata. Digita e verifica i comandi esatti, i messaggi di errore, gli URL e i numeri di versione prima di condividerla.

Cosa deve includere una segnalazione di bug?

Includi un titolo descrittivo, il contesto iniziale, i passaggi ordinati, il risultato atteso, quello effettivo, l’ambiente pertinente e prove sicure se necessarie. Segui il modello di segnalazione del repository, se disponibile.

Come segnalo un bug che non riesco a riprodurre?

Dichiara che è successo una volta o a intermittenza, annota ciò che hai osservato e l’ambiente che conosci e indica quali tentativi non sono riusciti a riprodurlo. Non colmare con ipotesi i passaggi sconosciuti.

Devo allegare i registri a una segnalazione pubblica?

Solo dopo averli controllati per individuare informazioni riservate e dati personali. Rimuovi o oscura i dati sensibili e condividi l’estratto più breve che aiuti a spiegare il problema. Segui le regole del tuo team sugli incidenti e sulla privacy.

Scarica Talkpad gratuitamente – 2.500 parole a settimana con il piano gratuito.