Release notes di emergenza: scrivere sotto vera pressione
5 min di lettura
La maggior parte delle release notes viene scritta dopo che il codice è pronto, revisionata con calma, e pubblicata secondo un calendario che non ha nulla a che fare con quanto urgentemente qualcuno ha bisogno di leggerla. Un rilascio d’emergenza, una patch di sicurezza, un bug di perdita dati, la correzione di un’interruzione, capovolge tutte quelle condizioni insieme: le note devono esistere prima che la maggior parte delle persone normalmente inizierebbe a scriverle, ricevono quasi nessuna revisione, e vengono lette da persone ansiose invece che rilassate. Come scrivere release notes copre il processo normale; questo riguarda cosa cambia quando non c’è più tempo per seguirlo.
Qual è l’unica cosa che una release note di emergenza deve assolutamente azzeccare?
Se chi legge deve fare qualcosa, dichiarato nella prima frase, senza alcuna cornice prima. Chi legge una release note guidata da un incidente è spesso già preoccupato, avendo sentito parlare del problema da una pagina di stato, un thread di supporto, o le proprie utenti, e una nota che apre con contesto prima dell’azione richiesta si legge come trattenere informazioni proprio nelle circostanze in cui trattenere si legge peggio. “Nessuna azione necessaria, questo corregge una vulnerabilità che non richiedeva dati utente per essere sfruttata” e “Aggiornate immediatamente: questo rilascio corregge un bug che poteva mostrare i dati di un account a un altro” sono entrambe una frase, ed entrambe fanno tutto il lavoro di cui ha bisogno chi legge nel panico prima di leggere qualsiasi altra cosa.
Il solito passaggio di editing si applica ancora quando non c’è tempo per farlo?
L’istinto di comprimere sopravvive anche quando il processo a più bozze che di solito lo produce non lo fa. La riscrittura descrive il tagliare una prima bozza prolissa fino alla sua frase essenziale; sotto pressione di tempo spesso non c’è una prima bozza da tagliare, il che significa che la disciplina deve girare nella vostra testa mentre scrivete invece che come passaggio separato dopo. Il modo più veloce per approssimarla: scrivete la frase che direste ad alta voce a qualcuno che chiede “cosa devo sapere”, poi fermatevi, perché quella frase è di solito sia la più veloce da produrre sia l’unica che chi legge in quello stato processerà davvero.
| Release note normale | Release note di emergenza |
|---|---|
| Scritta dopo la code review, prima della pubblicazione | Spesso scritta insieme alla correzione, prima della revisione completa |
| Ottimizzata per la scorribilità tra molte voci | Ottimizzata per una voce letta isolatamente, sotto stress |
| Può rimandare il dettaglio a un changelog collegato | Dovrebbe anteporre l’unico fatto più importante |
| Cornice e contesto sono benvenuti | La cornice prima dell’azione richiesta si legge come ritardo |
È mai accettabile pubblicare una nota prima di essere del tutto sicuri di cosa abbia causato il problema?
Sì, se la nota è onesta su quell’incertezza invece di suggerire una certezza che non avete. “Abbiamo distribuito una correzione per tassi di errore elevati nel checkout; stiamo ancora confermando la causa radice e aggiorneremo questa nota” è difendibile e guadagna tempo correttamente; una nota che afferma una causa specifica che in realtà non avete confermato è il tipo di ipotesi che diventa ciò che la gente vi cita indietro più tardi se risulta sbagliata. La disciplina che conta qui non è la velocità di diagnosi, è non lasciare mai che la certezza della nota superi la certezza reale del team, perché un’affermazione tecnica sbagliata in una nota di emergenza fa più danno alla fiducia di un’incognita ammessa.
Troppo sicuro, non verificato:
"Corretto: una race condition nel gestore del webhook
di pagamento causava addebiti duplicati."
Onesto sotto pressione di tempo:
"Corretto: ad alcune clienti è stato addebitato due volte
un singolo ordine. Abbiamo fermato nuove occorrenze e
stiamo rimborsando gli account interessati entro 24 ore.
Stiamo indagando la causa radice."Una nota di emergenza dovrebbe dire cosa ha causato il problema, o solo che è stato corretto?
Dite cosa è corretto e cosa dovrebbe fare chi legge; conservate la causa radice per un follow-up una volta che è davvero nota, non ipotizzata. Chi legge nel mezzo di un incidente vuole esattamente due fatti, se questo è risolto e se lo riguarda, e una spiegazione della causa radice, anche accurata, compete con quei due fatti per l’attenzione nel momento peggiore possibile per perderla. Il postmortem, pubblicato separatamente una volta finita l’indagine, è dove appartiene la causa radice; mescolare i due documenti sotto pressione di tempo produce una nota più lenta da scrivere e più lenta da leggere, l’opposto di ciò di cui ha bisogno un’emergenza.
Il problema dell’aggiornamento forzato delle app mobile si applica anche qui?
Lo stesso principio, ancora più compresso. Release notes per app mobile copre gli aggiornamenti forzati, dove la nota deve dichiarare il motivo e la scadenza prima di tutto perché chi legge è già infastidito dal non avere scelta; una release note di emergenza web è di solito opt-in per chi legge nel senso che sceglie se agire su di essa, ma lo stesso istinto “dichiarate prima il vincolo” si applica, solo per una ragione diversa: non fastidio, urgenza.
Come evitate che una nota di emergenza si legga come un’ammissione di colpa quando non dovrebbe?
Descrivete la correzione e il suo effetto, non la colpa, e resistete all’impulso di scusarvi eccessivamente, il che si legge come riempitivo per chi legge e vuole i due fatti sopra. “Abbiamo trovato e corretto un bug che riguardava alcune esportazioni” dice cosa è successo senza assegnargli dramma; “Siamo incredibilmente dispiaciuti per questo grave problema che ha colpito le nostre preziose clienti” ritarda l’informazione utile di un’intera frase per consegnare un momento emotivo che chi legge non ha chiesto. Una nota breve e fattuale non è fredda, è rispettosa dello stato reale di chi legge, che sotto vera pressione è impazienza, non bisogno di rassicurazione.
FAQ
Una release note di emergenza dovrebbe passare attraverso lo stesso processo di revisione di una normale? Uno più leggero, non nessuno: una singola revisora veloce che controlla che la nota non esageri la certezza vale i pochi minuti che costa, perché il rischio che un’affermazione tecnica non revisionata sia sbagliata è più alto proprio perché è stata scritta velocemente.
Va bene pubblicare una nota di emergenza senza alcun link a ulteriori dettagli? Solo brevemente. Una nota senza link funziona come la prima cosa pubblicata; aggiungetene uno a una pagina di stato o un follow-up appena esiste uno dei due, perché chi legge e vuole più dell’unica frase che avete dato ha bisogno di un posto dove andare, anche se quel posto dice “maggiori dettagli presto”.
Una nota di emergenza dovrebbe mai essere saltata del tutto, lasciando che la correzione venga distribuita in silenzio? Solo per problemi che nessuna lettrice avrebbe potuto notare o esserne stata colpita; se c’è qualche possibilità che una lettrice abbia sperimentato il problema, la nota è ciò che le dice che è finito, e il silenzio si legge come se il problema potesse ancora essere attivo.
Per quanto tempo una nota di emergenza dovrebbe restare fissata o prominente dopo che l’incidente è risolto? Finché la finestra di ansia immediata non si chiude, tipicamente un giorno o due, poi può confluire nel changelog normale come qualsiasi altra voce; una nota che resta fissata per settimane inizia a leggersi come una preoccupazione irrisolta invece che risolta.
Le affermazioni tecniche di questo articolo non sono state verificate in modo indipendente. Se qualcosa non è corretto, faccelo sapere e lo correggeremo.