Sjabloon voor release notes

Het sjabloon

Alles tussen vierkante haken is een tijdelijke aanduiding. Al het andere is de moeite waard om te bewaren, inclusief de volgorde: de lezer zoekt wat hem aangaat, dus belangrijke wijzigingen komen eerst en intern werk verschijnt helemaal niet.

## [Product] [versie] - [datum]

[Eén zin over waar dit release voor dient. Weglaten bij routine-releases.]

### Belangrijke wijzigingen
- [Wat stopt met werken, wat te doen in plaats daarvan, en tegen wanneer.
  Link naar de migratiestappen.]

### Nieuw
- [Functie, beschreven als resultaat. "Zet een filter vast en gebruik het
  opnieuw", niet "SavedView-model toegevoegd".]

### Verbeterd
- [Wat sneller, duidelijker of betrouwbaarder is, en ongeveer hoeveel.]

### Opgelost
- [Het symptoom dat de gebruiker zag, niet de oorzaak in de code.]

Als een sectie leeg is, verwijder dan de kop. Een lege sectie Opgelost geeft de indruk dat er niets is opgelost, en een kop zonder inhoud doet lezers denken dat de pagina niet goed is geladen.

Hetzelfde sjabloon, ingevuld

Zo ziet het eruit met echte inhoud. Merk op dat geen enkel item een bestand, een branch, een ticketnummer of een persoon noemt, en dat de belangrijke wijziging begint met de actie die de lezer moet ondernemen.

## Acme API 4.2 - 20 augustus 2026

Paginering werkt nu met een cursor op alle lijst-endpoints.

### Belangrijke wijzigingen
- `?page=` wordt verwijderd op alle lijst-endpoints. Gebruik de waarde
  `nextCursor` uit het vorige antwoord. `?page=` geeft na 1 oktober
  2026 een 400. Migratiestappen: acme.example/docs/pagination

### Nieuw
- Opgeslagen weergaven in de inbox. Zet een filter één keer vast en
  gebruik het opnieuw vanuit de zijbalk.
- Webhooks kunnen nu worden beperkt tot één project.

### Verbeterd
- Lijst-endpoints reageren ongeveer vier keer sneller bij grote accounts.
- De exportjob toont nu voortgang in plaats van vast te lijken.

### Opgelost
- Uitgenodigde leden zien niet langer een leeg dashboard vóór hun
  eerste keer inloggen.
- Tijdstempels in exports houden nu rekening met de tijdzone van het
  account.

Wat in elke sectie hoort

Belangrijke wijzigingen

De enige sectie met een deadline. Zeg wat stopt met werken, wat er in plaats daarvan te doen is, en vanaf welke datum. Heb je de datum nog niet bepaald, publiceer de sectie dan nog niet: een belangrijke wijziging zonder datum leest als urgent, en een reeks valse urgenties leert mensen je release notes te negeren.

Nieuw

Beschrijf het resultaat, niet wat je hebt gebouwd. De test is of de regel nog steeds zin heeft voor iemand die je code nooit heeft gezien. 'Opgeslagen weergaven in de inbox' slaagt. 'SavedView-model en migratie toegevoegd' niet.

Verbeterd

Kwantificeer waar je dat eerlijk kunt. 'Sneller' is bijna niets waard en wordt genegeerd; 'ongeveer vier keer sneller bij grote accounts' is de moeite van het lezen waard en zet een verwachting waar je op kunt worden aangesproken. Kun je het niet meten, zeg dan op een toetsbare manier wat er beter is.

Opgelost

Schrijf het symptoom, niet de oorzaak. Mensen zoeken in deze notities naar wat hen is overkomen, dus 'uitgenodigde leden zagen een leeg dashboard' is vindbaar en 'race condition in de membership-cache opgelost' niet.

Varianten

De vier secties werken voor de meeste releases. Drie gevallen vragen om een aanpassing:

• Releases van mobiele apps. App stores tonen een kort veld met nieuws, begin dus met een zin die leesbaar is in de store-vermelding, en verwijs dan naar de volledige notities. De review van de store kan een release ook dagen vertragen, dateer de notities dus op releasedatum, niet op mergedatum.
• API-releases. Versioneer de notities zoals je de API versioneert, en zet het deprecatievenster in de notities zelf, niet alleen in de documentatie. Wie een API gebruikt, leest de notities juist om te weten hoeveel tijd er nog rest.
• Interne of beheertools. Verwijder de sectie Verbeterd en voeg die samen met Opgelost. Interne gebruikers interesseert het of hun workflow is veranderd, en een lange sectie Verbeterd begraaft dat.

Vier regels die ze leesbaar houden

1. Schrijf voor iemand die je code niet kent. Geen bestandsnamen, geen branchnamen, geen ticket-id's, geen servicenamen, geen interne codenamen.
2. Laat alles weg dat geen zichtbaar effect heeft voor de gebruiker. Dependency-updates, refactors, CI-wijzigingen en typfoutcorrecties horen in de commitgeschiedenis, niet in de release notes. De meest gebruikelijke manier waarop release notes doodgaan, is door vol te raken met werk dat niemand buiten het team kan zien.
3. Eén item, één wijziging. Als een regel het woord 'en' twee keer nodig heeft, zijn het waarschijnlijk twee items.
4. Publiceer op een ritme waar mensen op kunnen rekenen, ook al is dat ritme 'telkens als we uitleveren'. Notities die vier keer per week verschijnen en dan twee maanden niet, worden als ruis gezien.

Format van release notes: de onderdelen, in volgorde

Het format telt minder dan de volgorde. Welke koppenstijl je ook gebruikt, wie release notes scant zoekt dezelfde vier dingen in dezelfde volgorde, en elk populair format is daar een variant van.

1. Een titel die zegt wat er voor de lezer is veranderd, niet het versienummer. De versie komt op een kleinere regel eronder, met de datum in ISO-formaat (2026-08-29), zodat die overal hetzelfde leest.
2. Belangrijke wijzigingen en alles met een deadline, eerst, ook al zijn ze klein. Als iemand na één alinea stopt met lezen, is dit de alinea die diegene nodig had.
3. Wat nieuw is, één punt per alinea, met het resultaat in de eerste zin en de vereiste actie, inclusief 'geen actie nodig', altijd vermeld.
4. Oplossingen en verbeteringen, dan al het overige als een lijst van één regel onderaan. Dependency-updates en interne wijzigingen blijven staan, omdat de ene persoon die ernaar zoekt ze echt nodig heeft.

In Markdown is dat een H2-titel, een gedempte regel met versie en datum, dan H3-secties voor Belangrijke wijzigingen, Nieuw, Verbeterd en Opgelost. In een e-mail is het dezelfde volgorde met de titel als onderwerp. In een changelog-widget zijn het de titel en de eerste alinea, met de rest achter een link. Het sjabloon hierboven is precies die vorm, uitgeschreven.

Voor het schrijven zelf, meer dan voor de vorm, zie Hoe schrijf je release notes die mensen echt lezen en Beste practices voor release notes die het waard zijn op de blog.

Veelgestelde vragen

Hoe lang moeten release notes zijn?

Zo lang als de wijzigingen die gebruikers raken, en geen regel langer. Een release met één bugfix verdient twee regels. Een kleine release opblazen om die substantieel te laten lijken, leert mensen de grote te overslaan.

Wat is het verschil tussen release notes en een changelog?

In de praktijk worden de termen door elkaar gebruikt. Waar teams ze wel onderscheiden, beschrijven release notes één release en zijn ze geschreven voor gebruikers, terwijl een changelog de doorlopende lijst is van alle releases in de tijd. Dit sjabloon dekt één release; een changelog krijg je door ze te stapelen, nieuwste eerst.

Moeten release notes een versienummer hebben?

Alleen als je gebruikers het kunnen zien. Versienummers zijn nuttig voor API's, bibliotheken en geïnstalleerde software, waar iemand moet weten op welke versie hij zit. Voor een continu uitgeleverde webapp is de datum nuttiger, omdat dat is wat de gebruiker kan vergelijken met wat hij zelf ervoer.

Wie moet ze schrijven?

Wie weet wat er is veranderd, meestal degene die het heeft samengevoegd, bewerkt door wie de toon bewaakt. De manier waarop dit misgaat, door ze volledig over te laten aan iemand buiten het werk, zijn notities die het ticket beschrijven in plaats van de wijziging.