Release notes zijn een korte samenvatting die uitlegt wat er in een nieuwe softwareversie is veranderd. Ze zijn voor mensen geschreven, niet voor machines: een lijst in gewone taal met de nieuwe features, de opgeloste bugs en alles wat je vooraf wilt weten voordat je update.
Denk aan het ‘Wat is er nieuw’-paneel dat je ziet als een app op je telefoon bijwerkt. Dat kleine scherm is de release note en vertelt je of deze versie een donkere modus toevoegde of alleen een crash verhielp. Erachter volgt het versienummer meestal een afspraak die semantische versionering heet, dus een sprong van 2.4.1 naar 2.4.2 wijst op een kleine patch, terwijl een sprong naar 3.0.0 waarschuwt voor grotere veranderingen.
Goede notes zijn eerlijk en concreet. ‘Opgelost: facturen boven 10.000 euro werden niet verstuurd’ is nuttig; ‘diverse verbeteringen’ zegt niemand iets. Ze leggen ook een spoor vast, zodat maanden later iedereen precies kan zien wat er live ging en wanneer.
De meest waardevolle regel is vaak de waarschuwing. Dwingt een wijziging elke gebruiker om zijn wachtwoord te resetten, of verplaatst hij een knop waar mensen op vertrouwden, dan zeg je dat in de release note gewoon hardop, voordat de supportinbox volloopt. Daarom schrijven teams de notes meestal al tijdens het bouwen van de feature, niet als bijzaak aan het eind. Doe je ze als laatste, dan vergeet je de helft, en juist dan glippen de vervelende verrassingen door naar je gebruikers.
Het loont ook om de notes te groeperen naar wie het aangaat. Een kort lijstje met wijzigingen voor gebruikers bovenaan, en verderop een aparte technische sectie voor je eigen developers. Het marketingteam tilt het eerste deel zo in een mailtje, terwijl support het volledige overzicht bij de hand houdt. Eén bron, twee doelgroepen, en niemand hoeft jargon voor de ander te vertalen.
Bij TopDevs schrijven we bij elke update heldere release notes, zodat je altijd weet wat er in je software veranderde en waarom, zonder dat je ernaar hoeft te vragen.
