Cum se scriu release notes pe care oamenii chiar le citesc

Pentru a scrie release notes pe care oamenii le citesc, răspundeți la o singură întrebare pe intrare: ce poate face cititorul acum, ce nu putea face înainte, și ce trebuie să facă în legătură cu asta. Puneți primul orice are un termen limită, numiți pe cine afectează, spuneți “nu e necesară nicio acțiune” când e adevărat, și săriți peste versiunile care n-au nimic de spus. Tot restul acestei pagini e această regulă aplicată.

Corecții de erori și îmbunătățiri de performanță.

Fiecare produs a publicat asta măcar o dată. Cauza e rareori lenea: asta obții când release notes sunt scrise din interior, de cineva care a petrecut două săptămâni în diff și nu mai poate vedea ce părți ar interesa un străin. Un ton mai bun nu va rezolva asta; a răspunde la întrebare, da.

Ce ar trebui să includă release notes?

Release notes ar trebui să includă, pentru fiecare schimbare care merită menționată: ce poate face cititorul acum, pe cine afectează, ce trebuie să facă (inclusiv “nimic”), și când intră în vigoare ceva cu un termen limită. Nu ar trebui să includă numere de tichete interne, nume de componente pe care le folosește doar echipa, sau un număr de versiune ca singur titlu.

Separarea dintre o release note și o intrare de changelog e ceea ce face posibilă această listă: changelog-ul păstrează totul, deci notele pot omite unele lucruri. Exemple adnotate pentru fiecare tip de intrare sunt adunate în exemple de release notes.

Întrebarea la care răspunde fiecare intrare

Ce poate face cititorul acum, ce nu putea face înainte, și ce trebuie să facă în legătură cu asta?

Dacă o intrare nu poate răspunde la asta, ea aparține changelog-ului, nu release notes. Ambele jumătăți contează. Prima jumătate e valoarea. A doua jumătate e cea pe care echipele o uită, și e cea care generează tichete de suport când lipsește.

Două exemple de a doua jumătate care face o treabă reală:

• “Webhook-urile existente vor continua să funcționeze până pe 1 noiembrie. După acea dată, payload-urile nesemnate vor fi respinse.”
• “Nu e necesară nicio acțiune. Exporturile existente sunt recodate automat data viitoare când le deschideți.”

A doua spune explicit “nu e necesară nicio acțiune”. Acea propoziție merită scrisă de fiecare dată, pentru că un cititor care n-o găsește presupune ce e mai rău.

Cum ar trebui ordonate release notes?

Ordonați-le după consecința pentru cititor, niciodată după partea sistemului care s-a schimbat. Gruparea după API, panou, mobil și infrastructură e organigrama voastră, nu problema cititorului.

1. Schimbările care rup compatibilitatea și orice are un termen limită. Mereu primele, chiar dacă e ceva mic. Dacă un cititor se oprește din citit după o linie, asta e linia pe care trebuia s-o citească. Dacă termenul limită e un sunset, intrarea ar trebui să sune ca o notificare de depreciere.
2. Ce e nou și vor dori. Câte unul pe paragraf, cu rezultatul în prima propoziție.
3. Ce s-a îmbunătățit. Erori raportate, limite ridicate, lucruri care erau lente.
4. Tot restul, ca listă. Actualizări de dependențe, refactorizări interne, text minor. Câte o linie fiecare. Nimeni nu citește această secțiune, și totuși trebuie să fie acolo, pentru că cine o caută chiar are nevoie de ea.

Rescrierea

Înainte:

v4.2.0 S-a corectat o problemă în care endpoint-ul POST /exports returna intermitent 500 sub sarcină. S-a refactorizat worker-ul de export. S-a actualizat node-pg la 8.11. S-a îmbunătățit gestionarea erorilor în serializatorul CSV.

După:

Exporturile nu mai eșuează pe conturi mari. Conturile cu peste aproximativ 50.000 de rânduri puteau primi un 500 la începerea unui export, mai des la sfârșitul lunii. Asta e rezolvat, iar exporturile de orice mărime încearcă acum din nou singure în loc să eșueze. Nu e necesară nicio acțiune, iar orice export care a eșuat săptămâna trecută poate fi pur și simplu rulat din nou.

Tot în 4.2.0: node-pg 8.11, erori mai clare în serializatorul CSV.

Aceeași versiune. A doua numește contul afectat, momentul în care a fost cel mai rău, ce s-a schimbat, și ce trebuie făcut. Actualizarea dependenței nu a dispărut, doar a încetat să fie titlul. Articolul cele mai bune practici pentru release notes are restul regulilor pe care le urmează această rescriere, fiecare cu costul de a le omite.

Lucruri care merită eliminate

• “Suntem încântați să anunțăm.” Cititorul nu e încă încântat. Câștigați asta în propoziția următoare.
• Numere de tichete interne. PROJ-4471 nu înseamnă nimic în afara tracker-ului vostru. Dacă intrarea are nevoie de o referință, faceți link la pagina de documentație.
• Nume de componente pe care le folosește doar echipa voastră. Dacă ați redenumit “pipeline-ul de ingestie”, spuneți “importuri”.
• Un număr de versiune ca singur titlu. v4.2.0 e o etichetă de arhivare, nu un rezumat.
• Capturi de ecran ale unei pagini de setări pe care n-a vizitat-o nimeni. Arătați ce s-a schimbat, în uz.

Cât de des ar trebui publicate release notes?

Publicați când s-a întâmplat ceva, nu după un program. Notele care sosesc la fiecare versiune îi învață pe toți să le ignore. Notele care sosesc când s-a întâmplat ceva sunt deschise. E în regulă, și de obicei corect, să lansați o versiune fără nicio notă și să rulați intrările ei în următorul set care are un titlu care merită citit.

Changelog-ul continuă să înregistreze totul. Asta e împărțirea muncii: changelog-ul e complet, notele sunt selective. Dacă mențineți changelog-ul structurat pe parcurs, scrierea notelor devine selecție și rescriere, nu arheologie.

Șablonul de release notes e forma pe care o folosim pentru etapa de selecție, iar exemple de changelog adună intrări de la echipe al căror changelog e suficient de bun încât să deriveze note din el.

Toate acestea presupun o pagină pe care o controlezi complet, fără limită de lungime și cu linkuri care funcționează. Note de lansare pentru aplicații mobile acoperă ce se schimbă când suprafața e o listare App Store sau Play Store. Note de lansare de urgență acoperă cealaltă excepție: ce se schimbă când nu mai rămâne deloc timp să urmați procesul normal de redactare.

Un test înainte de a publica

Citiți notele ca cineva care a fost în concediu două săptămâni și are 40 de secunde. Dacă, în acel timp, nu poate spune dacă i se cere ceva, notele nu sunt terminate, oricât de precise ar fi.

FAQ

Cât de lungi ar trebui să fie release notes? Atât de lungi cât cer schimbările cu consecințe, și nici o linie mai mult. O versiune cu o schimbare care rupe compatibilitatea și două îmbunătățiri sunt trei paragrafe. Umplerea unei versiuni liniștite ca să pară substanțială e cum învață cititorii să sară peste note.

Cine ar trebui să scrie release notes? Persoana care înțelege schimbarea, editată de cineva care nu o înțelege. Inginera știe ce s-a schimbat; editoarea știe ce va înțelege greșit un străin. Scrierea intrării la momentul merge-ului, cât timp inginera încă își amintește, e practica ce face asta ieftin.

Ar trebui release notes să includă corecții de erori? Da, cele pe care le-a raportat sau întâlnit cineva. Declarați simptomul văzut de cititor, nu cauza. “Exporturile de peste 50.000 de rânduri eșuau” e o corecție pe care un cititor o recunoaște; “s-a corectat o race condition în worker-ul de export” e un mesaj de commit.

Care e diferența dintre release notes și un changelog? Changelog-ul e registrul complet, continuu; release notes sunt mesajul selectat despre o versiune, scris pentru oameni care încă n-au decis dacă îi interesează. Răspunsul mai lung e în changelog vs release notes.

Afirmațiile tehnice din acest articol nu au fost verificate independent. Dacă ceva nu e corect, spune-ne și vom corecta.

Pe changeloop: Șablon note de lansare, Exemple de changelog