Wie man eine Changelog-Seite baut, die man abonniert

Eine Changelog-Seite lohnt sich, wenn jemand zu ihr zurückkehren würde. Das ist eine höhere Latte als bloß eine zu haben, und die meisten reißen sie: eine Seite, die existiert, im Footer verlinkt ist, in Schüben aktualisiert wird und von niemandem besucht wird außer während eines Incidents. Die Entscheidungen, die die zwei trennen, fallen bevor irgendetwas geschrieben wird, und meist geht es darum, wo die Seite lebt und was sonst aus demselben Inhalt erzeugt wird.

Was ist eine Changelog-Seite?

Es ist die öffentliche, datierte Liste dessen, was sich an einem Produkt geändert hat, auf einer URL, die euch gehört. Sie ist eine von fünf Oberflächen, auf denen dieselben Einträge erscheinen können, und die brauchbare Frage ist nicht, welche man wählt, sondern welche kanonisch ist und welche daraus erzeugt werden.

Wählt eine kanonische Quelle, veröffentlicht einmal, und erzeugt den Rest daraus. Teams, die die Seite und das Widget getrennt von Hand pflegen, enden mit zwei Texten, die sich widersprechen, und der Widerspruch wird von einem Kunden entdeckt.

Wo sollte eine Changelog-Seite leben?

Auf eurer eigenen Domain, auf einem stabilen Pfad, mit einer adressierbaren URL pro Eintrag. Die drei üblichen Platzierungen sind ein Pfad auf der Hauptseite, eine Subdomain, und ein Abschnitt der Dokumentation. Ein Pfad auf der Hauptseite ist die Voreinstellung, gegen die man argumentieren sollte statt für sie: Er erbt die Autorität der Seite, braucht kein zusätzliches Zertifikat oder DNS, und hält die Changelog-Seite in derselben Navigation wie alles andere.

Eine Subdomain ist die richtige Antwort, wenn die Seite von einem anderen System ausgeliefert wird als die Marketing-Seite und man sonst proxyen müsste. Der Preis ist, dass sie separat Autorität sammelt. Den Changelog in die Docs zu stecken ist richtig, wenn das Publikum Entwickler sind, aus dem Grund, der in API-Changelog behandelt wird: Der Leser ist meist schon in der Referenz.

Wichtiger als die Wahl ist, dass Einträge einzeln verlinkbar sind. Leute zitieren Einträge in Tickets, Incident Reviews und Support-Antworten. Ein Eintrag, der nur als “der Changelog, runter scrollen” verlinkt werden kann, wird stattdessen als Screenshot geteilt, und der Screenshot ist, was zirkuliert.

Was braucht eine Changelog-Seite?

Fünf Dinge, und bei den ersten beiden scheitern die meisten Seiten. Ein datierter Eintrag pro Änderung, neueste zuerst. Eine Kategorie oder ein Label pro Eintrag, damit man nach der Art scrollen kann, die einen interessiert. Ein Permalink pro Eintrag. Ein Abo-Weg. Eine Suche oder ein Filter, sobald es über etwa fünfzig Einträge sind.

Alles andere ist optional. Screenshots helfen und kosten Pflege. Autorennamen bauen bei manchen Produkten Vertrauen auf und sind bei anderen Rauschen. Versionsnummern sind für Aufrufer einer API wichtig und für fast niemanden sonst. Keep a Changelog ist eine vernünftige Voreinstellung für Labels, falls ihr keinen Grund habt, eigene zu erfinden, und seine Regel, dass das Log für Menschen geschrieben ist, ist die, die man behalten sollte, falls man den Rest verwirft.

Gruppiert nach Datum statt nach Release, wenn euer Produkt kontinuierlich ausliefert. Ein Leser, der scannt “war das vor oder nach unserem Incident am Neunten”, sucht ein Datum, und eine nach Versionsnummer organisierte Seite zwingt ihn zum Rechnen.

Seite oder In-App-Widget?

Beides, aus einer Quelle. Die Seite ist, wo Suche, Links und das lange Protokoll leben. Das Widget ist, wie man die Mehrheit der Nutzer erreicht, die die Seite nie besuchen werden, und es funktioniert, weil es im Produkt erscheint, das sie schon benutzen.

Der Fehlschlag des Widgets ist Unterbrechung. Ein Badge, das für jeden Eintrag Aufmerksamkeit verlangt, wird innerhalb einer Woche dauerhaft weggeklickt, was einen den Kanal für den Eintrag kostet, der wichtig war. Zählt ungelesen ab dem letzten Blick, seedet den Zähler still bei einem ersten Besuch, damit niemand von einem Badge für ein Jahr Historie begrüßt wird, und lasst den Leser es öffnen statt es für ihn zu öffnen.

Wie macht man eine Changelog-Seite maschinenlesbar?

Veröffentlicht dieselben Einträge als Feed. Ein JSON-Feed ist die reibungsärmere Option für alles, was ihn in Code konsumiert, und ein RSS-Feed ist, was ein Entwickler erwartet, der in einem Reader abonniert. Beides kostet wenig, sobald Einträge strukturierte Daten sind statt handgeschriebenem HTML, was das eigentliche Argument dafür ist, die kanonische Kopie strukturiert zu halten.

Markiert die Seite auch aus. Einträge sind Werke mit Datum und Titel, und schema.org liefert das Vokabular. Das lohnt sich aus demselben Grund wie die Permalinks: Es macht die Seite nutzbar für Dinge, die kein Browser sind, einschließlich dem eigenen Release-Prozess eines Kunden. Nichts davon funktioniert, wenn die zugrunde liegenden Einträge nie strukturierte Daten waren; Changelog-Dateiformate behandelt, was Markdown, JSON und YAML jeweils kosten als die Quelle der Wahrheit, aus der dieser Feed und dieses Markup tatsächlich generiert werden.

Hilft eine Changelog-Seite bei SEO?

Indirekt und langsam. Einzelne Einträge ranken selten, weil sie auf keine Query zielen, die jemand tippt. Die Seite verdient sich ihren Platz über Links: Einträge werden in Support-Antworten, Forenbeiträgen und Incident-Aufarbeitungen zitiert, und diese Links sammeln sich auf einer URL, die euch gehört. Eine Seite, die zwei Jahre lang wöchentlich aktualisiert wird, ist außerdem ein glaubwürdiges Frische-Signal für das Produkt, zu dem sie gehört.

Was nicht funktioniert, ist, Einträge als Content-Marketing zu behandeln. Ein Eintrag, der zu drei Absätzen aufgepolstert wird, ist schlechter in seiner eigentlichen Aufgabe, nämlich einem Leser in einem Satz zu sagen, ob sich etwas geändert hat, das er nutzt. Wenn der Changelog Suche unterstützen soll, steckt den Aufwand in die Permalinks, den Feed und die internen Links dorthin, und lasst die Einträge kurz. Unsere eigene Seite Changelog-Beispiele sammelt Seiten, die diese Balance richtig treffen.

Wie abonnieren Leute?

Gebt ihnen die Wege, die sie schon nutzen: einen RSS- oder JSON-Feed für Entwickler, E-Mail für Leute, die nur die wichtigen hören wollen, und das In-App-Widget für alle, die keins von beidem je tun werden. Fragt, was sie hören wollen, statt es anzunehmen, denn ein Leser, der Breaking Changes will und Text-Fixes bekommt, meldet sich von beidem ab.

Der Weg, den man zuletzt hinzufügen sollte, ist der, der den Loop schließt. Wenn ein Eintrag löst, was eine bestimmte Person angefragt hat, sagt es dieser Person direkt, statt zu hoffen, dass sie die Seite liest. In changeloop wird der Eintrag auf einmal auf der Seite, im Feed und im Widget veröffentlicht, und eine Person, deren Widget-Feedback zu dem GitHub-Issue wurde, das der Pull Request geschlossen hat, wird auf diesem Issue mit Link zum Eintrag informiert und sieht den Eintrag im Widget. Die Mechanik ist dieselbe wie bei jedem Abo; der Unterschied ist, dass der Empfänger schon gefragt hat. Das ist das Argument, das ausführlich in den Feedback-Loop vom Changelog aus schließen gemacht wird.

FAQ

Sollte die Changelog-Seite auf einer Subdomain oder einem Pfad liegen? Standardmäßig ein Pfad auf der Hauptseite, weil er die Autorität der Seite erbt und keine zusätzliche Infrastruktur braucht. Eine Subdomain ist gerechtfertigt, wenn ein anderes System die Seite ausliefert.

Wie viele Einträge sollte die Seite auf einmal zeigen? Genug, um einen Bildschirm zu füllen, und nicht mehr, mit Pagination danach. Zwei Jahre Historie in ein Dokument zu laden ist langsam und macht den neuesten Eintrag schwerer zu finden.

Sollten alte Einträge je gelöscht werden? Nein. Sie werden von außerhalb eurer Seite zitiert, und die Links brechen. Korrigiert einen Eintrag an Ort und Stelle mit einem Hinweis, und haltet die URL am Leben.

Muss jede Änderung auf der Seite erscheinen? Nur die, die ein Nutzer bemerken könnte. Eine Seite, die interne Refactorings protokolliert, trainiert Leser zum Überfliegen, und eine überflogene Seite scheitert an dem Tag, an dem sie etwas Dringendes trägt.

Die technischen Aussagen in diesem Artikel wurden nicht unabhängig geprüft. Wenn etwas nicht stimmt, sagen Sie es uns, und wir korrigieren es.

Mehr bei changeloop: Changelog-Beispiele, Entwicklerdokumentation