Release notes voor mobiele apps: wat de limiet wegsnijdt

Alles in dit hub over release notes schrijven veronderstelt een pagina die je volledig controleert: elke lengte, links die werken, opmaak die rendert. De release notes van een mobiele app leven in de doos van iemand anders. Apple geeft ongeveer 4.000 tekens maar toont alleen de eerste paar regels voordat “meer” wordt getikt; Google geeft vergelijkbare ruimte met hetzelfde effectieve voorbeeldprobleem, en geen van beide platformen rendert een klikbare link in de tekst. De regels uit release notes schrijven die mensen echt lezen gelden nog steeds: zeg wat er veranderde en wat de lezer moet doen, maar de ruimte om dat te doen is een fractie van wat een changelog-pagina toelaat, en de keuzes moeten weloverwogen zijn, niet per ongeluk.

Wat past er eigenlijk in het zichtbare voorbeeld?

De eerste een of twee regels, ongeveer 80 tot 170 tekens afhankelijk van apparaat en lettergrootte, voordat een lezer moet tikken om uit te klappen. Dat is het hele budget voor het deel van de release note dat bepaalt of iemand de rest gaat lezen, en het betekent dat de belangrijkste zin eerst moet komen, niet het versienummer, geen begroeting, geen categoriekop. Een release note die begint met “Nieuw in deze versie:” heeft al een derde van zijn zichtbare ruimte besteed aan vier woorden die de lezer niets vertellen.

Werkt de regel “wat kun je nu, wat ben je verschuldigd” nog op deze lengte?

Ja, en hij wordt strenger, niet anders. Eén zin per entry, werkwoord eerst, geen inleiding: “Exporteer je gegevens als CSV vanuit Instellingen.” wint van “We hebben de mogelijkheid toegevoegd voor gebruikers om nu hun gegevens in CSV-formaat te exporteren” door een derde van de woorden te gebruiken om hetzelfde te zeggen. Op de lengte van een changelog-pagina kost een wat breedsprakige zin een lezer een halve seconde. Op de lengte van een mobiele release note kan diezelfde breedsprakigheid de zin helemaal buiten het zichtbare voorbeeld duwen, zodat de lezer het werkwoord dat had verteld wat er veranderde nooit ziet.

Slecht, verspilt het voorbeeld aan de omlijsting:
"We zijn verheugd om je een nieuwe update vol
verbeteringen te brengen! Lees verder voor details."

Goed, alle waarde in de eerste regel:
"Exporteer je gegevens als CSV. Donkere modus volgt nu
de systeeminstelling. Crash bij openen van gedeelde
links verholpen."

Wat moet er weg dat een web-changelog-entry normaal zou behouden?

Links, eerst, omdat geen van beide stores ze klikbaar rendert, dus een URL in de tekst is dood gewicht dat een lezer zou moeten overtypen. Als de entry een bestemming nodig heeft, zeg dan in plaats daarvan wat er in de app getikt moet worden: “Zie de nieuwe filters onder Instellingen > Zoeken” werkt; “Lees meer op example.com/blog/filters” niet, op dit oppervlak. Ten tweede, alles wat voorwaardelijk of doelgroepspecifiek is: een web-changelog kan zeggen “als je de API gebruikt, raakt dit jou”, maar een winkelvermelding bereikt elke geïnstalleerde gebruiker tegelijk, dus een voorwaardelijke regel leest als ruis voor de 95% waarop het niet van toepassing is. Zet het voorwaardelijke detail in plaats daarvan in een in-app-bericht, getriggerd voor de accounts die het echt betreft.

Moet elke release zijn eigen notes krijgen, of is het oké om “bugfixes en prestatieverbeteringen” te hergebruiken?

Hergebruik het voor releases die dat oprecht zijn, maar controleer hoe vaak dat echt waar is. Release notes schrijven behandelt al waarom die zin een note verraadt die van binnenuit is geschreven in plaats van voor de lezer; op mobiel richt het dubbele schade aan, omdat winkel-release-notes een van de weinige plekken zijn waar sommige gebruikers tussen updates door überhaupt iets zien, en een lange reeks “bugfixes en prestatieverbeteringen” leest alsof de app niet verandert, wat een slechtere indruk maakt dan helemaal geen notes voor die periode.

Beïnvloeden release notes of mensen de app überhaupt updaten?

Indirect, via zichtbaarheid in plaats van overtuiging. De meeste gebruikers updaten automatisch en lezen de notes nooit voor het updaten; de notes tellen het meest voor de minderheid die updates handmatig controleert, en voor recensenten of pers die de geschiedenis van een winkelvermelding doorbladeren. Schrijven voor dat kleinere publiek betaalt zich toch uit, omdat een vermelding met een echte geschiedenis van specifieke, gedateerde entries leest als een actief onderhouden app, en een vermelding met een jaar “bugfixes en prestatieverbeteringen” niet, ongeacht hoeveel er in die tijd echt werd uitgebracht.

En een geforceerde update, waarbij de note moet uitleggen waarom de gebruiker geen keuze heeft?

Vermeld de reden en de deadline in de eerste regel, voor al het andere, want een geforceerde update is het ene geval waarin de lezer al geïrriteerd is voordat hij begint te lezen. “Deze update is nodig om je gegevens te blijven synchroniseren. Update voor [datum] om onderbreking te voorkomen.” zegt in één zin wat te doen en waarom; die reden begraven onder drie regels ongerelateerde featurenotes leest alsof de app het vervelende deel verbergt.

FAQ

Moeten mobiele release notes overeenkomen met de web-changelog van dezelfde release? Dezelfde onderliggende wijzigingen dekken, maar niet woord voor woord. De web-changelog kan zich de volledige uitleg veroorloven; de mobiele note heeft dezelfde feiten nodig, samengeperst tot een zin met het werkwoord eerst, wat meestal betekent dat het een herschrijving is, geen kopie.

Is het de moeite waard om mobiele release notes te lokaliseren voor elke ondersteunde taal? Ja, meer dan voor een web-changelog, omdat de winkelvermelding vaak het enige gelokaliseerde oppervlak is dat sommige gebruikers tussen sessies zien, en beide platformen ondersteunen release notes per locale zonder extra engineeringwerk buiten de vertaling zelf.

Hoe lang zou een mobiele release note moeten zijn als er geen limiet is die beknoptheid afdwingt? Kort sowieso. Het plafond van 4.000 tekens op iOS is zelden de echte beperking; dat is het voorbeeld van 2-3 regels, en schrijven voorbij wat dat voorbeeld toont, betekent alleen dat minder mensen het deel lezen dat ertoe deed.

Hebben release notes het versienummer nodig in de zichtbare tekst? Nee. De store toont het versienummer al naast de notes. Het herhalen in de tekst besteedt zichtbare tekens aan informatie die de lezer al voor zich heeft.

De technische beweringen in dit artikel zijn niet onafhankelijk gecontroleerd. Klopt er iets niet, laat het ons weten, dan corrigeren we het.

Meer op changeloop: Sjabloon voor release notes, Changelog-voorbeelden