Segnalare un errore in modo riproducibile
Di Redazione Quaderno dei Sistemi
Prepara una segnalazione con contesto, passi, risultato atteso e risultato osservato. Riduci i dati sensibili e separa i fatti dalle ipotesi.
Una segnalazione utile permette a un’altra persona di capire il problema senza indovinare che cosa è successo. «Non funziona» descrive una frustrazione, non una sequenza verificabile. Parti dall’operazione concreta e annota il risultato osservato prima di formulare una spiegazione.
Quattro elementi essenziali
Scrivi ambiente e versione, passi eseguiti, risultato atteso e risultato ottenuto. Se l’errore compare solo con un file, prepara quando possibile un esempio minimo privo di dati personali. Non allegare interi archivi di lavoro soltanto perché è più rapido.
Separare osservazione e ipotesi
«Il programma si chiude dopo aver scelto il file» è un’osservazione. «La memoria è insufficiente» è un’ipotesi, finché non hai elementi per sostenerla. Metti le due cose in sezioni diverse. Indica anche se il problema si ripete e quali tentativi non hanno cambiato il risultato.
Usare il canale previsto
Se il progetto usa GitHub Issues, verifica che le segnalazioni siano abilitate e cerca un caso già aperto. La piattaforma consente di descrivere problemi e richieste, ma il modello di segnalazione dipende dal progetto. Segui i campi richiesti e non pubblicare password, token o dati di clienti.
Concludi con una domanda operativa: quale informazione manca per riprodurre il caso? Un buon rapporto riduce il lavoro di ricostruzione. Non deve dimostrare che hai già individuato la causa, e non promette un tempo di risposta da parte del manutentore.
Continua a leggere
- Organizzare un manuale software per attività
- Schermate nei manuali: mostrare il passaggio senza nascondere il testo