Come scrivere release notes che la gente legge davvero

Per scrivere release notes che la gente legge, rispondi a una domanda per ogni voce: cosa può fare ora il lettore che prima non poteva, e cosa deve fare al riguardo. Metti per prima qualsiasi cosa con una scadenza, nomina chi è interessato, di’ “nessuna azione necessaria” quando è vero, e salta i rilasci che non hanno nulla da dire. Tutto il resto in questa pagina è quella regola applicata.

Correzioni di bug e miglioramenti delle prestazioni.

Ogni prodotto lo ha pubblicato almeno una volta. La causa raramente è pigrizia: è quello che si ottiene quando le release notes sono scritte dall’interno, da qualcuno che ha passato due settimane nel diff e non riesce più a vedere quali parti importerebbero a uno sconosciuto. Un tono migliore non lo risolverà; rispondere alla domanda sì.

Cosa dovrebbero includere le release notes?

Le release notes dovrebbero includere, per ogni cambiamento degno di nota: cosa può fare ora il lettore, chi è interessato, cosa deve fare al riguardo (incluso “niente”), e quando entra in vigore qualsiasi cosa con una scadenza. Non dovrebbero includere numeri di ticket interni, nomi di componenti usati solo dal team, o un numero di versione come unico titolo.

La divisione tra una release note e una voce di changelog è ciò che rende possibile questa lista: il changelog tiene tutto, così le notes possono lasciare fuori delle cose. Esempi annotati di ogni tipo di voce sono raccolti in esempi di release notes.

La domanda a cui risponde ogni voce

Cosa può fare ora il lettore che prima non poteva, e cosa deve fare al riguardo?

Se una voce non può rispondere a questo, appartiene al changelog e non alle release notes. Entrambe le metà contano. La prima metà è il valore. La seconda metà è quella che i team dimenticano, ed è quella che genera ticket di supporto quando manca.

Due esempi della seconda metà che fa un lavoro reale:

• “I webhook esistenti continuano a funzionare fino al 1° novembre. Dopo quella data, i payload non firmati verranno rifiutati.”
• “Nessuna azione necessaria. Le esportazioni esistenti vengono ricodificate automaticamente la prossima volta che le apri.”

La seconda dice esplicitamente “nessuna azione necessaria”. Vale la pena scrivere quella frase ogni singola volta, perché un lettore che non la trova presume il peggio.

Come dovrebbero essere ordinate le release notes?

Ordinale per conseguenza sul lettore, mai per la parte del sistema che è cambiata. Raggruppare per API, dashboard, mobile e infrastruttura è il vostro organigramma, non il problema del lettore.

1. Cambiamenti che rompono qualcosa e qualsiasi cosa con scadenza. Sempre per primi, anche se piccoli. Se un lettore smette di leggere dopo una riga, questa è la riga che deve aver letto. Se la scadenza è un sunset, la voce dovrebbe suonare come un avviso di deprecazione.
2. Cosa c’è di nuovo che vorranno. Uno per paragrafo, con il risultato nella prima frase.
3. Cosa è migliorato. Bug segnalati, limiti alzati, cose che erano lente.
4. Tutto il resto, come lista. Aggiornamenti di dipendenze, refactor interni, copy minore. Una riga ciascuno. Nessuno legge questa sezione, e dovrebbe comunque esserci, perché chi la cerca ne ha davvero bisogno.

La riscrittura

Prima:

v4.2.0 Corretto un problema per cui l’endpoint POST /exports restituiva intermittentemente 500 sotto carico. Rifattorizzato il worker di export. Aggiornato node-pg a 8.11. Migliorata la gestione errori nel serializzatore CSV.

Dopo:

Le esportazioni non falliscono più sugli account grandi. Gli account con oltre circa 50.000 righe potevano ricevere un 500 all’avvio di un’esportazione, più spesso a fine mese. Questo è risolto, e le esportazioni di qualsiasi dimensione ora si riprovano da sole invece di fallire. Nessuna azione necessaria, e qualsiasi esportazione fallita nell’ultima settimana può semplicemente essere rieseguita.

Anche nella 4.2.0: node-pg 8.11, errori più chiari nel serializzatore CSV.

Stesso rilascio. La seconda nomina l’account interessato, il momento peggiore, cosa è cambiato, e cosa fare. L’aggiornamento della dipendenza non è scomparso, ha solo smesso di essere il titolo. L’articolo buone pratiche per le release notes ha il resto delle regole che questa riscrittura segue, ciascuna con quanto costa saltarla.

Cose che vale la pena eliminare

• “Siamo entusiasti di annunciare.” Il lettore non è ancora entusiasta. Guadagnatelo nella frase successiva.
• Numeri di ticket interni. PROJ-4471 non significa nulla fuori dal vostro tracker. Se la voce ha bisogno di un riferimento, linka la pagina della doc.
• Nomi di componenti usati solo dal vostro team. Se avete rinominato la “pipeline di ingest”, dite “importazioni”.
• Un numero di versione come unico titolo. v4.2.0 è un’etichetta di archiviazione, non un riassunto.
• Screenshot di una pagina impostazioni che nessuno ha mai visitato. Mostrate ciò che è cambiato, in uso.

Con che frequenza si dovrebbero pubblicare le release notes?

Pubblicate quando succede qualcosa, non secondo un calendario. Le note che arrivano ad ogni rilascio addestrano tutti a ignorarle. Le note che arrivano quando succede qualcosa vengono aperte. Va bene, ed è di solito corretto, pubblicare un rilascio senza alcuna nota e far confluire le sue voci nel set successivo che ha un titolo degno di lettura.

Il changelog continua a registrare tutto. Questa è la divisione del lavoro: il changelog è completo, le note sono selettive. Se mantieni il changelog strutturato man mano, scrivere le note è selezione e riscrittura, non archeologia.

La release notes template è la forma che usiamo per il passaggio di selezione, e esempi di changelog raccoglie voci di team il cui changelog è abbastanza buono da derivarne delle note.

Tutto questo presuppone una pagina che controlli completamente, senza limite di lunghezza e con link che funzionano. Release notes per app mobile copre cosa cambia quando la superficie è un elenco App Store o Play Store. Release notes di emergenza copre l’altra eccezione: cosa cambia quando non resta più tempo per seguire affatto il normale processo di scrittura.

Un test prima di pubblicare

Leggi le note come qualcuno che è stato in vacanza per due settimane e ha 40 secondi. Se in quel tempo non riesce a capire se gli viene richiesto qualcosa, le note non sono finite, per quanto accurate siano.

FAQ

Quanto dovrebbero essere lunghe le release notes? Quanto richiedono i cambiamenti con conseguenze, e non un pizzico di più. Un rilascio con un cambiamento che rompe qualcosa e due miglioramenti sono tre paragrafi. Riempire un rilascio tranquillo per farlo sembrare sostanzioso è come i lettori imparano a saltare le note.

Chi dovrebbe scrivere le release notes? La persona che capisce il cambiamento, editata da qualcuno che non lo capisce. L’ingegnera sa cosa è cambiato; l’editrice sa cosa fraintenderà uno sconosciuto. Scrivere la voce al momento del merge, mentre l’ingegnera se lo ricorda ancora, è la pratica che rende tutto questo economico.

Le release notes dovrebbero includere correzioni di bug? Sì, quelle che qualcuno ha segnalato o incontrato. Indica il sintomo visto dal lettore, non la causa. “Le esportazioni oltre 50.000 righe fallivano” è una correzione che un lettore riconosce; “corretta una race condition nel worker di export” è un messaggio di commit.

Qual è la differenza tra release notes e un changelog? Il changelog è il registro completo e continuo; le release notes sono il messaggio curato su un rilascio, scritto per persone che non hanno ancora deciso se interessarsi. La risposta più lunga è in changelog vs release notes.

Le affermazioni tecniche di questo articolo non sono state verificate in modo indipendente. Se qualcosa non è corretto, faccelo sapere e lo correggeremo.

Correlati su changeloop: Modello di release notes, Esempi di changelog