Wie schreibe ich ein Changelog, oder: Was man vom World of Warcraft-Changelog lernen kann

Die Dokumentation von Commits und die Kommentare in einem Changelog sind für die meisten Entwickler mehr Pflicht als Kür. Im Grunde ist man froh, den Bug oder das Feature endlich implementiert zu haben. Für eine sinnvolle Dokumentation bleibt keine Zeit, die nächsten 100 Tickets warten schon. Ausserdem: Wer liest schon Changelogs und Commits? Das tun ja nur Entwickler, demzufolge kann man auch das Entwicklerjargon verwenden: “fix: the api method had a typo in l 316″.Noch schneller: Fixes sind meist an Tickets gebunden. Also einfach die Ticketnummer rein, wer das liest, kann sich den Rest ja aus dem Bugtracker holen: “Fix: #12738″.

Die Konsequenz: Keiner liest Changelogs

Henne oder Ei: Weil Changelogs nicht gelesen werden, sind Kommentare so schlecht und werden so vernachlässigt? Oder: Weil Kommentare so schlecht sind, werden Changelogs nicht gelesen? Eines ist unumstritten: Wer Applikationen einsetzt und eventuell betreut, der muss die Changelogs lesen. Auch beim heutzutage gängigen Einsatz von Frameworks, ist das Durcharbeiten von Changelogs vor dem Update in der eigenen Applikation notwendig. Das kann – abhängig von der Kommentierfreude der Entwickler – eine lange, lange Angelegenheit werden. Man springt von Changelog zu Bugtracker zu Showcase, schreibt Testroutinen, um ggf. die eine oder andere Änderung zu verifizieren. Man scannt das soziale Netzwerk, ob evtl. diverse Auffälligkeiten zu ermitteln sind. Ab damit ins Testsystem, Integration prüfen. Deployment. Live. Puh!

Die World of Warcraft-Patchnotes

World of Warcraft ist ein Online-Spiel mit einer ungeheuren Menge Benutzern und einer Batterie Drittunternehmen, Redaktionen und Portale, die mittlerweile fest mit dem Erfolg des Spieles verknüpft sind. Es existieren gefühlte 10 Trillionen Plugins, 21 Trillionen Blogs und Portale mit Itemlisten, Guides, Spieledaten, usw. usw. Ein Patch von World of Warcraft ist immer ein Grossereignis, hat doch jeder zu prüfen, ob seine Einstellungen, seine Charakterplanung, ja, seine ganze Spielweise nach dem Patch noch so sein wird wie vorher.

Screenshot: World of Warcraft Patchnotes

Um gewisse Unstimmigkeiten zu vermeiden und um insgesamt den Horden von Spielern und Nutzniessern eine Unterstützung zu liefern, die a) wenig Fragen offen lässt und dadurch b) das Frage-Aufkommen auch vermutlich recht gering zu halten, werden die meist sehr, sehr umfangreichen Patchnotes in einer besonderen Tonalität geschrieben. Nach 4 Jahren Spiel und unzähligen Patches vermute ich hinter diesen Patchnotes die folgenden Regeln:

  • Ein Patchnote-Kommentar ist immer mindestens ein ganzer Satz
  • Ein Patchnote-Kommentar ist immer positiv, nicht negativ formuliert (Beispiel folgt)
  • Ein Patchnote-Kommentar beschreibt immer den Zustand nach dem Patch, niemals den Zustand davor
  • Ein Patchnote-Kommentar beschreibt immer den Gewinn eines Patches, nie den Verlust (Beispiel folgt)
  • Patchnote-Kommentare werden sinnhaft gruppiert
  • Ein Patchnote-Kommentar beschreibt immer den Effekt auf den Prozess, nicht das technische Detail (Beispiel folgt)
  • Ein Patchnote-Kommentar folgt im Normalfall der Twitter-Regel: 140 Zeichen sollten für die Beschreibung des Wesentlichen ausreichen

Durch diese paar Regeln und ein wenig mehr Elan und Kreativität bei der Erzeugung des Patch-Kommentars wird es den Lesern einfach gemacht, sich auf die Änderungen einzustellen. Noch mehr, durch die Tonalität neigen die meisten Leser bereits zu gewissen Verhaltensweisen, der psychologische Effekt ist enorm:

  • Durch die positive Formulierung und der Beschreibung des augenscheinlichen Gewinns, befasst sich der Betroffene weniger mit der Trauer über den Verlust einer Funktion oder ärgert sich über die Änderungen, die ihm Arbeit verursachen, stattdessen werden die Gedanken auf die neuen Möglichkeiten gerichtet, die nach einem Update oder Patch zur Verfügung stehen.
  • Der zusammenhängende Satz verhindert einen direkte Suche in sekundäre Informationsquellen und lässt den Leser in den Patchnote-Listen verbleiben. Der zusammenhängende Satz vermittelt auch ein wenig Ganzheitlichkeit: Wer zusammenhängende Sätze schreibt, wird sich sicherlich viele Gedanken um das Thema gemacht haben.

Beispiele: Positiv und negativ

Die folgenden Beispiele sind frei erfunden. Der positive Kommentar verhindert die Betroffenheit des Lesers, mit einer verbuggten Applikation zu arbeiten. Anstelle in einer Liste von 200 Kommentaren ca. 190 x zu lesen, welcher Bug vorhanden war und jetzt gefixt ist (negativ), wird beschrieben, welches Feature nun wie gewünscht funktioniert (positiv). Beispiel: In einer frühen Version wurde durch einen Fehler der Zeitstempel der letzten Bearbeitung eines Artikels nicht aktualisiert.

Negativ: Fix: Fehler in methode Article::update(), ts_lastupdate wurde nicht geschrieben. Klappt jetzt. 

Positiv: Der Zeitstempel der Bearbeitung eines Artikels wird nun korrekt gespeichert und angezeigt.

Beispiele: Gewinn und Verlust

Gerade für Entwickler ist es schmerzhaft, wenn beim Einsatz eines Frameworks nach einem Major Release ein bestimmtes Feature nicht mehr existiert oder anders funktioniert als vorher. Abhängig von der Qualität des Codes kann das schon mal mit einer Menge Nacharbeit verbunden sein, um die Applikation auf die Änderungen umzustellen. Wenn Patchnotes aber nicht nur den Verlust vermitteln, sondern auch die neuen Features beschreiben, die nun zur Verfügung stehen, ist der Entwickler manchmal in der Lage, dem neuen Zustand sogar etwas Gutes abzugewinnen, bzw. sein Konzept auf Basis der neuen Möglichkeiten sinnvoll zu überdenken. Beispiel: Aus Gründen der Performance muss eine einzelne Funktion in zwei neue aufgespaltet werden.

Verlust: Funktion xy ersetzt durch Funktion ab und ac. Xy darf nicht mehr verwendet werden. 

Gewinn: Mit den Funktionen ab und ac wird nun ein erheblicher Performancegewinn erzielt. Gleichzeitig können die einzelnen Funktionen für ihre jeweiligen Einsatzzwecke besser genutzt werden (s. Dokumentation ab und ac). Die Funktion xy ist veraltet und wird im nächsten Major Release nicht mehr vorhanden sein.

Beispiel: Effekt des Patches, nicht technisches Detail

Screenshot Patchnotes Smarty

Die Beschreibung eines technischen Details lenkt vom Effekt einer Veränderung ab. Der Leser muss sich zunächst mit den Eigenschaften der Technik auseinandersetzen, anstelle den Effekt nachvollziehen zu können. Beispiel: Aus Performancegründen und einigen Mängel wird eine Funktion zur Generierung einer Liste durch eine andere ersetzt.

Negativ: Fix: Die Funktion implode() verursacht Fehler. Ersetzt durch foreach-Schleife. 

Positiv: Es ist nun auch die Erzeugung großer Listen ohne Probleme möglich. Dazu wurde implode() durch foreach ersetzt.

Anmerkung: Vereinzelt kommt man um technische Details nicht herum. So werden auch Entwickler, die sich für die einzelnen Vorgehensweisen interessieren, nicht vernachlässigt.

Fazit, noch einige Kommentare und Beispiele

Mit ein paar kleinen Regeln können Changelogs und Patchnotes also durchaus ein interessanter und kurzweiliger Lesestoff werden. Mit ausführlichen Kommentaren ist auch die Grundlage für Diskussionen in Foren und Blogs durchweg besser. Ich arbeite gerade an meiner Gewohnheit, Patchnotes und Commits in Zukunft unter Berücksichtigung der o. g. Regeln zu schreiben. In ein paar Wochen werde ich die Betroffenen ansprechen und sie zu den Änderungen befragen. Ich bin sehr gespannt, was ich als Antwort bekomme.Obwohl ich die PHP-Template-Engine Smarty ganz gerne mag, sind die Changelogs oft ein abschreckendes Beispiel. Ein Positiv-Beispiel ist dagegen das World of Warcraft-Changelog. Es mag für einige Leser inhaltlich befremdlich sein, wenn man aber die ersten paar Kommentare liest, wird klar, welche Regeln hier zugrunde liegen und wie mein Artikel gemeint ist. Abhängig von der gepatchten Applikation ist es auch manchmal notwendig, parallel zu den Changelogs neue Features in einer besonderen Übersicht zu beschreiben, so wie es das jQuery-Team zumindest bei den Major Releases macht.Wie schreibt ihr eure Commits und Patchnotes?

Dieser Beitrag wurde unter Web-Entwicklung abgelegt und mit , , verschlagwortet. Setze ein Lesezeichen auf den Permalink.

2 Antworten auf Wie schreibe ich ein Changelog, oder: Was man vom World of Warcraft-Changelog lernen kann

  1. Pingback: Weltuntergangswatchblog - Links vom 8. Februar 2009

  2. Alexander sagt:

    Nice to know muss ich da mal sagen. Übrigends: DU bsit ganz oben, wenn man bei Google nach: “Wie schreibt man einen Changelog” sucht^^

Hinterlasse eine Antwort

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind markiert *

*

Du kannst folgende HTML-Tags benutzen: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>