Hoe schrijf je release notes die mensen echt lezen
6 min lezen bijgewerkt op
Om release notes te schrijven die mensen lezen, beantwoord één vraag per entry: wat kan de lezer nu doen dat eerst niet kon, en wat moet die daaraan doen. Zet alles met een deadline vooraan, noem wie het treft, zeg “geen actie nodig” als dat waar is, en sla releases over die niks te melden hebben. Al het andere op deze pagina is die regel toegepast.
Bugfixes en prestatieverbeteringen.
Elk product heeft dit ooit gepubliceerd. De oorzaak is zelden luiheid: dit krijg je als release notes van binnenuit worden geschreven, door iemand die twee weken in de diff heeft gezeten en niet meer kan zien welke delen een buitenstaander zouden interesseren. Een betere schrijfstijl lost dat niet op; de vraag beantwoorden wel.
Wat zouden release notes moeten bevatten?
Release notes zouden voor elke vermeldenswaardige verandering moeten bevatten: wat de lezer nu kan doen, wie het betreft, wat die moet doen (inclusief “niets”), en wanneer iets met een deadline ingaat. Ze zouden geen interne ticketnummers, componentnamen die alleen het team gebruikt, of een versienummer als enige kop moeten bevatten.
| Wel opnemen | Weglaten |
|---|---|
| Het resultaat, in de taal van de lezer | De implementatie, in de taal van het team |
| Wie het treft, per plan, rol of API-versie | “Sommige gebruikers” |
| De vereiste actie, of “geen actie nodig” | Stilte, die de lezer met het ergste scenario invult |
| Een datum voor alles met een deadline | Een versienummer in plaats van een datum |
| Een link naar de doc die het uitlegt | Een link naar de pull request |
| Bugs die zijn gemeld, en de limiet die omhoog ging | Interne ticket-id’s |
| De saaie sectie, elk één regel, onderaan | De saaie sectie vermengd met het nieuws |
Het onderscheid tussen een release note en een changelog-entry maakt deze lijst mogelijk: de changelog houdt alles bij, dus de notes mogen dingen weglaten. Geannoteerde voorbeelden van elk entrytype staan in release notes voorbeelden.
De vraag die elke entry beantwoordt
Wat kan de lezer nu doen dat eerst niet kon, en wat moet die daaraan doen?
Als een entry dat niet kan beantwoorden, hoort die in de changelog thuis en niet in de release notes. Beide helften tellen. De eerste helft is de waarde. De tweede helft is die de teams vergeten, en het is degene die supporttickets oplevert als hij ontbreekt.
Twee voorbeelden van de tweede helft die echt werk verzet:
- “Bestaande webhooks blijven werken tot 1 november. Daarna worden ongesigneerde payloads geweigerd.”
- “Geen actie nodig. Bestaande exports worden automatisch opnieuw gecodeerd de volgende keer dat je ze opent.”
De tweede zegt expliciet “geen actie nodig”. Die zin is elke keer weer het schrijven waard, omdat een lezer die hem niet vindt het ergste aanneemt.
Hoe zou je release notes moeten ordenen?
Orden ze naar gevolg voor de lezer, nooit naar het deel van het systeem dat veranderde. Groeperen op API, dashboard, mobiel en infrastructuur is jullie organogram, niet het probleem van de lezer.
- Breaking changes en alles met een deadline. Altijd eerst, ook als het klein is. Als een lezer na één regel stopt met lezen, is dit de regel die die gelezen moet hebben. Als de deadline een sunset is, zou de entry moeten klinken als een deprecatiebericht.
- Wat nieuw is en waar ze op zaten te wachten. Eén per alinea, met het resultaat in de eerste zin.
- Wat beter werd. Bugs die zijn gemeld, limieten die omhoog gingen, dingen die traag waren.
- Al het andere, als lijst. Dependency-updates, interne refactors, kleine copy. Elk één regel. Niemand leest deze sectie, en toch moet hij er zijn, want wie hem zoekt heeft hem echt nodig.
De herschrijving
Voor:
v4.2.0 Probleem opgelost waarbij het endpoint
POST /exportsaf en toe 500 teruggaf onder belasting. Export-worker gerefactored.node-pgbijgewerkt naar 8.11. Foutafhandeling in de CSV-serializer verbeterd.
Na:
Exports falen niet meer bij grote accounts. Accounts met ruim 50.000 rijen konden een 500 krijgen bij het starten van een export, vaker rond het einde van de maand. Dat is opgelost, en exports van elke omvang proberen zichzelf nu opnieuw in plaats van te falen. Geen actie nodig, en elke export die vorige week faalde kan gewoon opnieuw worden uitgevoerd.
Ook in 4.2.0:
node-pg8.11, duidelijkere fouten in de CSV-serializer.
Dezelfde release. De tweede noemt het getroffen account, het moment waarop het het ergst was, wat er veranderde, en wat te doen. De dependency-update is niet verdwenen, hij is alleen gestopt de kop te zijn. Het artikel beste practices voor release notes heeft de rest van de regels die deze herschrijving volgt, elk met wat het kost om ze over te slaan.
Dingen die het waard zijn om te schrappen
- “We zijn verheugd om aan te kondigen.” De lezer is nog niet verheugd. Verdien dat in de volgende zin.
- Interne ticketnummers.
PROJ-4471betekent niets buiten jullie tracker. Als de entry een verwijzing nodig heeft, link naar de docpagina. - Componentnamen die alleen jullie team gebruikt. Als je de “ingest-pipeline” hebt hernoemd, zeg dan “imports”.
- Een versienummer als enige kop.
v4.2.0is een archiveringslabel, geen samenvatting. - Screenshots van een instellingenpagina die niemand ooit bezocht. Toon wat er veranderd is, in gebruik.
Hoe vaak zou je release notes moeten publiceren?
Publiceer wanneer er iets is gebeurd, niet volgens een schema. Notes die bij elke release komen leren iedereen ze te negeren. Notes die komen wanneer er iets is gebeurd worden geopend. Het is prima, en meestal juist, om een release zonder enige note uit te brengen en de entries te laten meelopen in de volgende set die een kop heeft die de moeite van het lezen waard is.
De changelog blijft alles vastleggen. Dat is de taakverdeling: de changelog is compleet, de notes zijn selectief. Als je de changelog gaandeweg gestructureerd houdt, wordt het schrijven van de notes selectie en herschrijven in plaats van archeologie.
De release notes template is de vorm die we gebruiken voor de selectiestap, en changelog-voorbeelden verzamelt entries van teams wier changelog goed genoeg is om notes uit af te leiden.
Dit alles veronderstelt een pagina die je volledig controleert, zonder lengtelimiet en met links die werken. Release notes voor mobiele apps behandelt wat er verandert als het oppervlak een App Store- of Play Store-vermelding is. Noodrelease notes behandelt de andere uitzondering: wat er verandert als er helemaal geen tijd meer is om het normale schrijfproces te volgen.
Eén test voor je publiceert
Lees de notes als iemand die twee weken op vakantie is geweest en 40 seconden heeft. Als die persoon in die tijd niet kan zien of er iets van hem gevraagd wordt, zijn de notes niet af, hoe accuraat ze ook zijn.
FAQ
Hoe lang zouden release notes moeten zijn? Zo lang als de gevolgtrekkende veranderingen vereisen, en geen regel langer. Een release met één breaking change en twee verbeteringen is drie alinea’s. Een rustige release opvullen om substantieel te lijken is hoe lezers leren de notes over te slaan.
Wie zou release notes moeten schrijven? De persoon die de verandering begrijpt, geredigeerd door iemand die dat niet doet. De engineer weet wat er veranderd is; de redacteur weet wat een buitenstaander verkeerd zal lezen. De entry schrijven op het moment van de merge, terwijl de engineer het zich nog herinnert, is de praktijk die dit goedkoop maakt.
Zouden release notes bugfixes moeten bevatten? Ja, die iemand heeft gemeld of tegenkwam. Vermeld het symptoom dat de lezer zag, niet de oorzaak. “Exports van meer dan 50.000 rijen faalden” is een fix die een lezer herkent; “race condition in de export-worker opgelost” is een commitbericht.
Wat is het verschil tussen release notes en een changelog? De changelog is het complete, doorlopende register; de release notes zijn het gecureerde bericht over één release, geschreven voor mensen die nog niet hebben besloten of het ze interesseert. Het langere antwoord staat in changelog vs release notes.
De technische beweringen in dit artikel zijn niet onafhankelijk gecontroleerd. Klopt er iets niet, laat het ons weten, dan corrigeren we het.