Wie man Release Notes schreibt, die wirklich gelesen werden

Um Release Notes zu schreiben, die gelesen werden, beantworte pro Eintrag eine Frage: Was kann die Leserin jetzt tun, was vorher nicht ging, und was muss sie deswegen tun? Stelle alles mit einer Frist nach vorn, nenne, wer betroffen ist, sag “keine Aktion nötig”, wenn es stimmt, und lass Releases weg, die nichts zu sagen haben. Alles andere auf dieser Seite ist diese Regel angewendet.

Bugfixes und Performance-Verbesserungen.

Jedes Produkt hat das schon veröffentlicht. Die Ursache ist selten Faulheit: Das ist, was dabei herauskommt, wenn Release Notes von innen geschrieben werden, von jemandem, der zwei Wochen im Diff verbracht hat und nicht mehr sehen kann, welche Teile davon eine fremde Person interessieren würden. Ein besserer Tonfall behebt das nicht; die Frage zu beantworten schon.

Was sollten Release Notes enthalten?

Release Notes sollten für jede erwähnenswerte Änderung enthalten: was die Leserin jetzt tun kann, für wen es gilt, was sie deswegen tun muss (einschließlich “nichts”), und wann etwas mit Frist in Kraft tritt. Sie sollten keine internen Ticketnummern, nur teamintern bekannte Komponentennamen oder eine Versionsnummer als einzige Überschrift enthalten.

Die Trennung zwischen einer Release Note und einem Changelog-Eintrag macht diese Liste erst möglich: Der Changelog behält alles, sodass die Notes etwas weglassen können. Kommentierte Beispiele für jede Eintragsart sammeln die Release-Notes-Beispiele.

Die Frage, die jeder Eintrag beantwortet

Was kann die Leserin jetzt tun, was vorher nicht ging, und was muss sie deswegen tun?

Kann ein Eintrag das nicht beantworten, gehört er in den Changelog und nicht in die Release Notes. Beide Hälften zählen. Die erste Hälfte ist der Wert. Die zweite Hälfte ist der Teil, den Teams vergessen, und genau der erzeugt Support-Tickets, wenn er fehlt.

Zwei Beispiele, in denen die zweite Hälfte echte Arbeit leistet:

• “Bestehende Webhooks funktionieren bis zum 1. November weiter. Danach werden unsignierte Payloads abgelehnt.”
• “Keine Aktion nötig. Bestehende Exporte werden automatisch neu kodiert, sobald du sie das nächste Mal öffnest.”

Der zweite sagt explizit “keine Aktion nötig”. Diesen Satz zu schreiben lohnt sich jedes Mal, denn eine Leserin, die ihn nicht findet, nimmt das Schlimmste an.

Wie sollten Release Notes sortiert sein?

Sortiere nach Konsequenz für die Leserin, nie nach dem Teil des Systems, der sich geändert hat. Eine Gruppierung nach API, Dashboard, Mobile und Infrastruktur ist dein Organigramm, nicht das Problem der Leserin.

1. Breaking Changes und alles mit Frist. Immer zuerst, auch wenn es klein ist. Hört eine Leserin nach einer Zeile auf, muss das die gelesene Zeile gewesen sein. Ist die Frist ein Sunset, sollte der Eintrag wie eine Deprecation-Ankündigung klingen.
2. Was neu ist und gewollt wird. Ein Punkt pro Absatz, das Ergebnis im ersten Satzteil.
3. Was besser geworden ist. Gemeldete Fehler, angehobene Grenzen, langsame Dinge.
4. Alles andere, als Liste. Abhängigkeits-Updates, interne Refactorings, kleine Textänderungen. Je eine Zeile. Niemand liest diesen Abschnitt, und er sollte trotzdem da sein, weil die Person, die ihn sucht, ihn wirklich braucht.

Die Überarbeitung

Vorher:

v4.2.0 Behoben: Ein Problem, bei dem der Endpunkt POST /exports unter Last gelegentlich 500 zurückgab. Export-Worker überarbeitet. node-pg auf 8.11 angehoben. Fehlerbehandlung im CSV-Serializer verbessert.

Nachher:

Exporte schlagen bei großen Konten nicht mehr fehl. Konten mit etwa über 50.000 Zeilen konnten beim Start eines Exports einen 500er bekommen, häufiger zum Monatsende. Das ist behoben, und Exporte jeder Größe versuchen es jetzt selbst erneut, statt fehlzuschlagen. Keine Aktion nötig, und jeder Export, der in der letzten Woche fehlgeschlagen ist, kann einfach erneut gestartet werden.

Auch in 4.2.0: node-pg 8.11, klarere CSV-Serializer-Fehler.

Gleiches Release. Der zweite nennt das betroffene Konto, den Zeitpunkt, zu dem es am schlimmsten war, was sich geändert hat, und was zu tun ist. Das Abhängigkeits-Update ist nicht verschwunden, es hat nur aufgehört, die Überschrift zu sein. Der Artikel Release-Notes-Best-Practices enthält die restlichen Regeln, denen diese Überarbeitung folgt, jeweils mit den Kosten, sie zu überspringen.

Dinge, die es zu streichen lohnt

• “Wir freuen uns, ankündigen zu können.” Die Leserin ist noch nicht begeistert. Verdiene das im nächsten Satz.
• Interne Ticketnummern. PROJ-4471 bedeutet außerhalb eures Trackers nichts. Braucht der Eintrag einen Verweis, verlinke die Doku-Seite.
• Komponentennamen, die nur euer Team benutzt. Habt ihr die “Ingest-Pipeline” umbenannt, sagt “Importe”.
• Eine Versionsnummer als einzige Überschrift. v4.2.0 ist ein Ablagevermerk, keine Zusammenfassung.
• Screenshots einer Einstellungsseite, die niemand besucht hat. Zeig das, was sich geändert hat, in Benutzung.

Wie oft sollte man Release Notes veröffentlichen?

Veröffentliche, wenn etwas passiert ist, nicht nach Zeitplan. Notes, die zu jedem Release kommen, trainieren alle, sie zu ignorieren. Notes, die kommen, wenn etwas passiert ist, werden geöffnet. Es ist völlig in Ordnung, ein Release ganz ohne Notes zu veröffentlichen und seine Einträge in die nächste Runde zu übernehmen, die eine lesenswerte Überschrift hat.

Der Changelog verzeichnet trotzdem alles. Das ist die Arbeitsteilung: Der Changelog ist vollständig, die Notes sind selektiv. Hältst du den Changelog laufend strukturiert, ist das Schreiben der Notes Auswahl und Umformulierung statt Archäologie.

Die Release-Notes-Vorlage ist die Form, die wir für den Auswahlschritt nutzen, und Changelog-Beispiele sammelt Einträge von Teams, deren Changelog gut genug ist, um Notes daraus abzuleiten.

All das setzt eine Seite voraus, die man selbst kontrolliert, ohne Längenlimit und mit funktionierenden Links. Release Notes für mobile Apps behandelt, was sich ändert, wenn die Fläche ein App-Store- oder Play-Store-Eintrag ist. Notfall-Release-Notes behandelt die andere Ausnahme: was sich ändert, wenn überhaupt keine Zeit bleibt, den normalen Schreibprozess durchzuführen.

Ein Test vor der Veröffentlichung

Lies die Notes wie jemand, der zwei Wochen im Urlaub war und 40 Sekunden Zeit hat. Kann diese Person in dieser Zeit nicht sagen, ob etwas von ihr verlangt wird, sind die Notes nicht fertig, egal wie korrekt sie sind.

FAQ

Wie lang sollten Release Notes sein? So lang, wie die relevanten Änderungen es brauchen, und nicht länger. Ein Release mit einem Breaking Change und zwei Verbesserungen sind drei Absätze. Ein ruhiges Release aufzublähen, damit es bedeutend wirkt, ist der Weg, auf dem Leserinnen lernen, die Notes zu überspringen.

Wer sollte Release Notes schreiben? Die Person, die die Änderung versteht, redigiert von jemandem, der sie nicht versteht. Die Entwicklerin weiß, was sich geändert hat; die Redakteurin weiß, was eine fremde Person missversteht. Den Eintrag beim Merge zu schreiben, solange die Entwicklerin sich noch erinnert, ist die Praxis, die das günstig macht.

Sollten Release Notes Bugfixes enthalten? Ja, die, die jemand gemeldet hat oder auf die jemand gestoßen ist. Nenne das Symptom, das die Leserin gesehen hat, nicht die Ursache. “Exporte über 50.000 Zeilen schlugen fehl” ist ein Bugfix, den eine Leserin wiedererkennt; “Race Condition im Export-Worker behoben” ist eine Commit-Nachricht.

Was ist der Unterschied zwischen Release Notes und einem Changelog? Der Changelog ist die vollständige, laufende Aufzeichnung; die Release Notes sind die kuratierte Botschaft zu einem Release, geschrieben für Menschen, die noch nicht entschieden haben, ob es sie interessiert. Die längere Antwort steht in Changelog vs. Release Notes.

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: Vorlage für Release Notes, Changelog-Beispiele