Een changelogpagina bouwen die mensen blijven volgen

Een changelogpagina is de moeite van het bouwen waard als iemand erop zou terugkomen. Dat is een hogere lat dan er gewoon een hebben, en het is de lat waarop de meeste struikelen: een pagina die bestaat, gelinkt is in de footer, met horten en stoten wordt bijgewerkt en door niemand bezocht wordt behalve tijdens een incident. De beslissingen die de twee scheiden, worden genomen voordat er iets geschreven is, en gaan vooral over waar de pagina leeft en wat er nog meer uit dezelfde inhoud gegenereerd wordt.

Wat is een changelogpagina?

Het is de publieke, gedateerde lijst van wat er veranderd is in een product, op een URL die van jou is. Het is een van vijf oppervlakken waarop dezelfde items kunnen verschijnen, en de bruikbare vraag is niet welke je kiest maar welke canoniek is en welke ervan afgeleid worden.

Kies één canonieke bron, publiceer eenmaal, en genereer de rest. Teams die de pagina en de widget apart met de hand onderhouden, eindigen met twee teksten die niet overeenkomen, en een klant ontdekt de discrepantie.

Waar moet een changelogpagina leven?

Op je eigen domein, op een stabiel pad, met elk item afzonderlijk adresseerbaar. De drie gebruikelijke plekken zijn een pad op de hoofdsite, een subdomein, en een sectie van de documentatie. Een pad op de hoofdsite is de standaardkeuze waartegen je moet argumenteren, niet voor: het erft het gezag van de site, heeft geen extra certificaat of DNS nodig, en houdt de pagina in dezelfde navigatie als al het andere.

Een subdomein is het juiste antwoord als de pagina door een ander systeem wordt bediend dan de marketingsite en je anders zou proxyen. De kosten zijn dat het apart gezag opbouwt. De changelog in de docs zetten is juist als het publiek developers zijn, om de reden behandeld in API-changelog: de lezer is daar meestal al.

Belangrijker dan de keuze is dat items afzonderlijk linkbaar zijn. Mensen linken naar items in incidentanalyses en interne tickets, en een item dat alleen als “de changelog, scroll naar beneden” gelinkt kan worden, wordt in plaats daarvan als screenshot geplakt.

Wat heeft een changelogpagina nodig?

Vijf dingen, en op de eerste twee falen de meeste pagina’s. Een gedateerd item per wijziging, het nieuwste eerst. Een categorie of label per item om te kunnen scannen op het type dat je interesseert. Een permalink per item. Een abonneerroute. Een zoekfunctie of filter na ongeveer vijftig items.

De rest is optioneel. Screenshots helpen en kosten onderhoud. Auteursnamen bouwen vertrouwen op bij sommige producten en zijn ruis bij andere. Versienummers zijn belangrijk voor aanroepers van een API en voor bijna niemand anders. Keep a Changelog is een redelijke standaard voor labels als je geen reden hebt om eigen labels te verzinnen, en de kernregel is degene die je moet houden zelfs als je de rest weggooit: het logboek is geschreven voor mensen.

Groepeer op datum in plaats van op versie als je product continu uitbrengt. Een lezer die scant “was dit voor of na ons incident op de negende” zoekt een datum, en een pagina georganiseerd op versienummer dwingt hem te rekenen.

Pagina of widget in de app?

Beide, uit één bron. De pagina is waar zoeken, links en het lange overzicht leven. De widget is hoe je de meerderheid van gebruikers bereikt die de pagina nooit zullen bezoeken, en werkt omdat hij verschijnt in het product dat ze al gebruiken.

Het falen van de widget is onderbreking. Een badge die aandacht eist voor elk item wordt binnen een week permanent weggeklikt, wat je het kanaal kost voor het item dat er echt toe deed. Tel ongelezen sinds de laatste keer dat de lezer keek, zaai de teller stil bij het eerste bezoek zodat niemand begroet wordt met een badge van een jaar geschiedenis, en laat de lezer hem openen in plaats van hem voor hem te openen.

Hoe maak je een changelogpagina machineleesbaar?

Publiceer dezelfde items als feed. Een JSON-feed is de optie met de minste wrijving voor alles wat het in code consumeert, en een RSS-feed is wat een developer die zich abonneert in een reader verwacht. Beide kosten weinig zodra items gestructureerde data zijn in plaats van met de hand geschreven HTML, wat het echte argument is om de canonieke kopie gestructureerd te houden.

Markeer de pagina ook. Items zijn werken met een datum en een titel, en schema.org levert de vocabulaire. Dat is de moeite waard om dezelfde reden als de permalinks: het maakt de pagina bruikbaar voor dingen die geen browser zijn, inclusief het eigen releaseproces van een klant. Niets hiervan werkt als de onderliggende items nooit gestructureerde data waren om te beginnen; changelog-bestandsformaten behandelt wat Markdown, JSON en YAML elk kosten als de bron van waarheid waaruit deze feed en deze markup daadwerkelijk worden gegenereerd.

Helpt een changelogpagina de SEO?

Indirect en langzaam. Individuele items ranken zelden, omdat ze op geen enkele zoekopdracht mikken die iemand typt. De pagina verdient zijn plek via links: items worden geciteerd in supportantwoorden, forums en incidentanalyses, en die links stapelen zich op een URL die van jou is. Een pagina die twee jaar lang wekelijks wordt bijgewerkt, is ook een geloofwaardig versheidssignaal voor het product waartoe hij behoort.

Wat niet werkt, is items behandelen als contentmarketing. Een item opgeblazen tot drie alinea’s om het langer te maken, is slechter in zijn eigenlijke taak, namelijk een lezer in één zin vertellen of iets dat hij gebruikt veranderd is. Als je wilt dat de changelog zoeken ondersteunt, stop de moeite dan in de permalinks, de feed en de interne links ernaartoe, en houd de items kort. Onze eigen pagina met changelogvoorbeelden verzamelt pagina’s die deze balans goed raken.

Hoe abonneren mensen zich?

Geef ze de routes die ze al gebruiken: een RSS- of JSON-feed voor developers, e-mail voor wie alleen de belangrijke dingen wil horen, en de widget in de app voor iedereen die geen van beide ooit zal doen. Vraag wat ze willen horen in plaats van het aan te nemen, want een lezer die breaking changes wil en tekstcorrecties krijgt, meldt zich af van beide.

De route die je als laatste toevoegt, is degene die de loop sluit. Als een item oplost wat een specifieke persoon vroeg, vertel het hem dan direct in plaats van te hopen dat hij de pagina leest. Bij changeloop wordt het item in één keer gepubliceerd op de pagina, de feed en de widget, en een persoon wiens widgetfeedback het GitHub-issue werd dat de pull request sloot, wordt op dat issue op de hoogte gebracht met een link naar het item, en ziet het item in de widget. Het mechanisme is hetzelfde als elk abonnement; het verschil is dat de ontvanger al gevraagd heeft. Dat is het argument dat wordt uitgewerkt in de feedbackloop sluiten vanuit de changelog.

FAQ

Moet de changelogpagina op een subdomein of een pad staan? Standaard een pad op de hoofdsite, want dat erft het gezag van de site en heeft geen extra infrastructuur nodig. Een subdomein is gerechtvaardigd als een ander systeem de pagina bedient.

Hoeveel items moet de pagina tegelijk tonen? Genoeg om een scherm te vullen en niet meer, met paginering daarna. Twee jaar geschiedenis in één document laden is traag en maakt het nieuwste item moeilijker te vinden.

Moeten oude items ooit verwijderd worden? Nee. Ze worden geciteerd van buiten je site en de links breken. Corrigeer een item ter plaatse met een notitie, en houd de URL levend.

Moet elke wijziging op de pagina verschijnen? Alleen degene die een gebruiker zou kunnen opmerken. Een pagina die interne refactors logt, traint lezers om te scannen zonder te lezen, en een gescande pagina faalt op de dag dat hij iets dringends draagt.

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: Changelog-voorbeelden, Documentatie voor ontwikkelaars