Dies ist Teil zwei der zweiteiligen Serie zum Thema agile Dokumentation. Lesen Sie Teil eins hier. In diesem Artikel werde ich auf die wohl am häufigsten gestellte Frage zur Dokumentation eingehen: Wie hält man alles auf dem neuesten Stand?
Doch gehen wir zunächst auf unsere Ziele drei und vier für die Dokumentation eine.
Der gerade beschriebene Papier-Baukasten zur Erläuterung eines Datenmodells erfüllte neben der bloßen Informationsvermittlung noch einen weiteren Zweck. Die Datenbanktechnologie war in diesem Unternehmen eine ziemlich wichtige strategische Entscheidung vor unserer Zeit gewesen. Es hatte sich aber herausgestellt, dass sie für unser Team eine Menge Aufwand bedeutete, da sie für unseren Use Case nicht optimal geeignet war.
Mit dem Baukasten und einem Schritt-für-Schritt-Ansatz hatten wir eine effektive und wiederholbare Möglichkeit, unsere Anforderungen darzustellen und schnell Empathie und Verständnis für unsere Schwierigkeiten zu erlangen. Dadurch konnten die wiederholten Diskussionen mit ArchitektInnen und ExpertInnen weniger emotional, mehr effizient und faktengestützt geführt werden.
In ihrem Artikel über "Empathy Driven Development", spricht Duretti Hirpa von einer „empathischen Codebasis“. Um eine solche Codebasis aufzubauen, sollte man sich „jegliches Werkzeug zunutze machen, das Kontext schafft“, einschließlich Dokumentation. „Docs or it didn’t happen“.
Durch Dokumentation zeigen wir Empathie gegenüber unseren TeamkollegInnen und gestalten eine Umgebung, in der sich insbesondere jüngere oder neuere Teammitglieder beim Ändern der Software geleitet und sicher fühlen. Dieses Ziel gilt insbesondere für die Kategorie von Dokumentation, die vornehmlich für neue Teammitglieder erstellt wird (z.B. Readme-Dateien), oder Hilfe für Troubleshooting (z.B. Firefighting-Checklisten für Dinge, die noch nicht automatisiert sind).
Ein Beispiel: Als wir in einem Team einen PDF-Dokumentengenerator bauten, berichtete uns die Product Ownerin beinahe jeden Tag, dass jemandem ein bestimmter Seitenumbruch nicht gefiel, der durch den Layout-Algorithmus automatisch gesetzt wurde. Entsprechende Korrekturen am Algorithmus führten oft zu neuen Problemen, oder brachten Fehler zurück, die wir in der Vorwoche erst beseitigt hatten. Um diese Diskussionen zu vereinfachen, erstellten wir ein Poster, auf dem die Logik des Algorithmus für den Seitenumbruch beschrieben wurde. So konnten wir zeigen, wie die Einführung neuer Regeln bestehende Regeln aushebelten. Wir konnten dann auf Augenhöhe miteinander über die Prioritäten sprechen. Indem wir die Logik für beide Seiten verständlich darstellten, halfen wir auch den Beta-Benutzern, sich in uns hineinzuversetzen und den Umfang der Implementierung besser zu verstehen. Wir hatten dann das Gefühl, diese Funktion wirklich als Team einzuführen, und nicht als zwei gegensätzliche Parteien von „Anforderern“ und „Implementierern“.
Geeignete Kandidaten finden
Indem wir, wie oben beschrieben, Übersichten erstellen, die die Komplexität von Lösungen verdeutlichen, können wir auch bei anderen „Techies“ Empathie wecken. Sie verstehen dann besser, warum die Lösung des Problems schwierig war. So entsteht eine solide Grundlage für eine konstruktive Diskussion und gegenseitiges Lernen.
Aber was tun, wenn man das Problem gar nicht mehr beschreiben kann, weil niemand mehr weiß, was das Problem ursprünglich mal war?
Michael Nygard beschreibt in einem Blogartikel von 2011 das Konzept der „Architecture Decision Records“. Er beschreibt darin seine Beobachtung, dass die Motivationen hinter bestimmten Entscheidungen bei vielen Projekten oft besonders schwierig nachzuverfolgen sind. Wer die Motivation nicht verstehe, könne eine Entscheidung nur entweder „blind akzeptieren“ oder „blind ändern“. Um unsere Blindheit in der Zukunft zu vermeiden, sollten wir Begründung, Kontext und Konsequenzen einer Entscheidung unmittelbar aufzuschreiben.
Es gibt viele Werkzeuge, mit denen Sie solche Entscheidungen festhalten können – vom Word-Dokument über ein Wiki bis hin zu einfachen Textdateien. Ich selbst habe dieses kleine Tool in der Vergangenheit erfolgreich genutzt, um Markdown-Dateien zu erstellen, die dann mit dem Code versioniert wurden. Das Werkzeug an sich ist hier jedoch nicht die Herausforderung. Die eigentliche Schwierigkeit liegt darin, diese wirklich wertvolle Art der Dokumentation Routine werden zu lassen. Wir müssen uns angewöhnen, nach einer Entscheidung nicht direkt zur Umsetzung zu springen, sondern kurz innezuhalten, um die noch frischen Zusammenhänge direkt zu dokumentieren.
Geeignete Kandidaten für Decision Records finden
Wenn Sie einmal ein Gespür und eine Routine für Decision Records entwickelt haben, denken Sie daran, nicht nur die gewählte Lösung zu dokumentieren, sondern auch das Problem und den Kontext. Wenn Sie beispielsweise aufschreiben, dass Sie Technologie X gewählt haben, weil sie skalierbar ist und Docker unterstützt, dann listen Sie damit Merkmale Ihrer Lösung auf, aber nicht die Gründe, wieso Sie diese benötigen. Warum muss die Lösung skalierbar sein, und warum brauchen Sie die Docker-Unterstützung? Mithilfe dieser Begründung können Sie in Zukunft besser entscheiden, ob sich diese Umstände geändert haben und inzwischen auch eine weniger skalierbare Lösung oder eine Lösung ohne Docker infrage kommt. Die von Nygard empfohlene Struktur „Kontext – Entscheidung – Konsequenzen“ hilft mir persönlich dabei, mich auf die Problembeschreibung zu konzentrieren.
Im Folgenden möchte ich einige Prinzipien vorstellen, mit denen ich versuche, die abstraktere, nicht ausführbare Dokumentation so aktuell wie möglich zu halten.
So wenig Dokumentation wie möglich zu haben, ist auf lange Sicht der beste Schutz vor veralteter Dokumentation. Je mehr Details Sie hinzufügen, desto höher ist die Wahrscheinlichkeit, dass Sie sie bald aktualisieren müssen. Überlegen Sie auch hier, welchen Nutzen ein dokumentiertes Element oder ein Detail hat, und bedenken Sie dabei, dass Sie es pflegen müssen – genau wie jede einzelne Zeile des Codes, den Sie schreiben.
Und scheuen Sie sich auch nicht, immer mal wieder Dokumentation wegzuschmeißen. Manche der oben beschriebenen Beispiele sind nur vorübergehend nützlich, und das kann auch valide sein.
Denken Sie darüber nach, wie Sie die Pflege der Dokumentation in Ihre Teamrituale einbeziehen können. Ein wöchentlicher „Developer Huddle“ (auch manchmal „Show-and-Tell“ genannt) kann hier helfen. In diesem Wochentermin bespricht das Team technische Themen und Fragen, die sich im Laufe der Woche ergeben haben. „Gibt es was zu dokumentieren?“ kann hier als Checkpoint auf der Agenda stehen.
Sie sollten außerdem die Rotation von Teammitgliedern nutzen, um die aktuelle Nützlichkeit und Verständlichkeit Ihrer Dokumentation zu überprüfen.
Erstellen Sie Dokumentation kollaborativ im Team erstellen, damit jeder sich für sie verantwortlich fühlt. Dies führt zu gemeinsamer „Ownership“ der Dokumentation, was die Wahrscheinlichkeit erhöht, dass alle Teammitglieder ein Auge auf die Artefakte haben und sie bei Bedarf aktualisieren. Wenn nur eine Person im Team die Dokumentation erstellt, kommt diese Einzelkämpferin langfristig nicht allein hinterher.
Besonderes Augenmerk sollten Sie deshalb auf das haben, was der Code nicht verraten kann: Historie und Kontext. „Selbsterklärender“ Code hilft Ihnen nicht dabei, vergangene Entscheidungen zu überdenken oder zu verstehen, wieso etwas auf eine bestimmte Art implementiert wurde. Das Minimum sollte also sein, wichtige Entscheidungen zu dokumentieren. Auch eine gute Pflege Ihrer Commit-Messages mit Begründungen für kleine Design-Entscheidungen kann hier helfen.
Ich hoffe meine Beispiele haben auch gezeigt, dass das Erstellen und Pflegen von Dokumentation auch für einige andere der agilen Prinzipien ausschlaggebend sein kann, z. B. „Einfachheit“, „Fachexperten und Entwickler müssen täglich zusammenarbeiten“, „Augenmerk auf technische Exzellenz und gutes Design“ oder „In regelmäßigen Abständen reflektiert das Team, wie es effektiver werden kann“.
Wenn Sie dazu neigen, viel Dokumentation zu erstellen, und Sie „Waste“ reduzieren wollen: Priorisieren Sie, indem Sie sich auf den Mehrwert und Nutzen der Dokumentation konzentrieren. Beobachten Sie auch, welche Dokumentation Sie am Ende wirklich verwenden, und welche Sie nie wieder anschauen. Scheuen Sie sich nicht davor, Dinge zu löschen.
Wenn Sie eher sehr wenig Dokumentation erstellen: Überlegen Sie noch einmal, ob Ihnen einige der hier beschriebenen Mehrwerte fehlen, und welche Arten der Dokumentation Ihrem Team helfen würden, effektiver zu arbeiten.
Doch gehen wir zunächst auf unsere Ziele drei und vier für die Dokumentation eine.
3. Empathie wecken
Dokumentation schafft Verständnis – aber nicht nur in dem Sinne, dass eine Person den Code oder die Architektur inhaltlich besser versteht, sondern auch Verständnis im Sinne von Empathie zwischen den Beteiligten.
Empathie zwischen Technologie-EntscheiderInnen und EntwicklerInnen
Der gerade beschriebene Papier-Baukasten zur Erläuterung eines Datenmodells erfüllte neben der bloßen Informationsvermittlung noch einen weiteren Zweck. Die Datenbanktechnologie war in diesem Unternehmen eine ziemlich wichtige strategische Entscheidung vor unserer Zeit gewesen. Es hatte sich aber herausgestellt, dass sie für unser Team eine Menge Aufwand bedeutete, da sie für unseren Use Case nicht optimal geeignet war.
Mit dem Baukasten und einem Schritt-für-Schritt-Ansatz hatten wir eine effektive und wiederholbare Möglichkeit, unsere Anforderungen darzustellen und schnell Empathie und Verständnis für unsere Schwierigkeiten zu erlangen. Dadurch konnten die wiederholten Diskussionen mit ArchitektInnen und ExpertInnen weniger emotional, mehr effizient und faktengestützt geführt werden.
Empathie zwischen EntwicklerInnen
Working on software without guidance, without documentation, is anxiety-producing.
In ihrem Artikel über "Empathy Driven Development", spricht Duretti Hirpa von einer „empathischen Codebasis“. Um eine solche Codebasis aufzubauen, sollte man sich „jegliches Werkzeug zunutze machen, das Kontext schafft“, einschließlich Dokumentation. „Docs or it didn’t happen“.
Durch Dokumentation zeigen wir Empathie gegenüber unseren TeamkollegInnen und gestalten eine Umgebung, in der sich insbesondere jüngere oder neuere Teammitglieder beim Ändern der Software geleitet und sicher fühlen. Dieses Ziel gilt insbesondere für die Kategorie von Dokumentation, die vornehmlich für neue Teammitglieder erstellt wird (z.B. Readme-Dateien), oder Hilfe für Troubleshooting (z.B. Firefighting-Checklisten für Dinge, die noch nicht automatisiert sind).
Empathie zwischen EntwicklerInnen und Nicht-EntwicklerInnen
Nicht selten habe ich beobachtet, wie EntwicklerInnen über ihre KollegInnen aus dem Produktmanagement sagen, dass diese einfach nicht richtig verstehen würden wie die Software wirklich funktioniert. Mit etwas Kreativität und Mühe bei der Dokumentation können EntwicklerInnen auch diese Lücke kleiner machen.Ein Beispiel: Als wir in einem Team einen PDF-Dokumentengenerator bauten, berichtete uns die Product Ownerin beinahe jeden Tag, dass jemandem ein bestimmter Seitenumbruch nicht gefiel, der durch den Layout-Algorithmus automatisch gesetzt wurde. Entsprechende Korrekturen am Algorithmus führten oft zu neuen Problemen, oder brachten Fehler zurück, die wir in der Vorwoche erst beseitigt hatten. Um diese Diskussionen zu vereinfachen, erstellten wir ein Poster, auf dem die Logik des Algorithmus für den Seitenumbruch beschrieben wurde. So konnten wir zeigen, wie die Einführung neuer Regeln bestehende Regeln aushebelten. Wir konnten dann auf Augenhöhe miteinander über die Prioritäten sprechen. Indem wir die Logik für beide Seiten verständlich darstellten, halfen wir auch den Beta-Benutzern, sich in uns hineinzuversetzen und den Umfang der Implementierung besser zu verstehen. Wir hatten dann das Gefühl, diese Funktion wirklich als Team einzuführen, und nicht als zwei gegensätzliche Parteien von „Anforderern“ und „Implementierern“.
Geeignete Kandidaten finden
- Wenn viele Bugs gemeldet werden, die auf ein Missverständnis eines Features zurückzuführen sind.
- Features, die eine Änderungsphase durchlaufen und denen ein ausgefeiltes Regel- und Logiksystem zugrunde liegt. Alle Beteiligten müssen die Logik verstehen, damit sie gemeinsam an der Änderung arbeiten können.
4. Bessere Entscheidungen treffen
“If you look at another engineer's work and think, ‘That's dumb. Why don't you just…’ Take a breath. Find out why the problem is hard.” Adrienne Porter FeltIndem wir, wie oben beschrieben, Übersichten erstellen, die die Komplexität von Lösungen verdeutlichen, können wir auch bei anderen „Techies“ Empathie wecken. Sie verstehen dann besser, warum die Lösung des Problems schwierig war. So entsteht eine solide Grundlage für eine konstruktive Diskussion und gegenseitiges Lernen.
Aber was tun, wenn man das Problem gar nicht mehr beschreiben kann, weil niemand mehr weiß, was das Problem ursprünglich mal war?
Dokumentieren von Architektur-Entscheidungen
Michael Nygard beschreibt in einem Blogartikel von 2011 das Konzept der „Architecture Decision Records“. Er beschreibt darin seine Beobachtung, dass die Motivationen hinter bestimmten Entscheidungen bei vielen Projekten oft besonders schwierig nachzuverfolgen sind. Wer die Motivation nicht verstehe, könne eine Entscheidung nur entweder „blind akzeptieren“ oder „blind ändern“. Um unsere Blindheit in der Zukunft zu vermeiden, sollten wir Begründung, Kontext und Konsequenzen einer Entscheidung unmittelbar aufzuschreiben.
Es gibt viele Werkzeuge, mit denen Sie solche Entscheidungen festhalten können – vom Word-Dokument über ein Wiki bis hin zu einfachen Textdateien. Ich selbst habe dieses kleine Tool in der Vergangenheit erfolgreich genutzt, um Markdown-Dateien zu erstellen, die dann mit dem Code versioniert wurden. Das Werkzeug an sich ist hier jedoch nicht die Herausforderung. Die eigentliche Schwierigkeit liegt darin, diese wirklich wertvolle Art der Dokumentation Routine werden zu lassen. Wir müssen uns angewöhnen, nach einer Entscheidung nicht direkt zur Umsetzung zu springen, sondern kurz innezuhalten, um die noch frischen Zusammenhänge direkt zu dokumentieren.
Geeignete Kandidaten für Decision Records finden
- Entscheidungen, denen lange Diskussionen vorangingen
- Entscheidungen, die sich nur schwer ändern lassen
- Stellen Sie sich vor, Sie bekommen ein neues Teammitglied: Würde er oder sie die Entscheidung ohne weiteren Kontext infrage stellen?
- Regelmäßig angezweifelte Entscheidungen. Ein Beispiel: Alle zwei oder drei Monate hinterfragt ein Teammitglied die Entscheidung für Technologie X, aber nach einer Überprüfung wird klar, dass es eigentlich gute Gründe für die Entscheidung gab. Mit der Aufzeichnung der ursprünglichen Entscheidung, inklusive der Anforderungen, kann effizienter mit solchen „Whac-A-Mole“ Entscheidungen umgegangen werden. In der Regel ist es dann nur noch erforderlich, die Liste der Anforderungen in der Aufzeichnung durchzugehen und zu fragen: „Hat sich das Problem oder der Kontext in irgendeiner Form geändert?”
Wenn Sie einmal ein Gespür und eine Routine für Decision Records entwickelt haben, denken Sie daran, nicht nur die gewählte Lösung zu dokumentieren, sondern auch das Problem und den Kontext. Wenn Sie beispielsweise aufschreiben, dass Sie Technologie X gewählt haben, weil sie skalierbar ist und Docker unterstützt, dann listen Sie damit Merkmale Ihrer Lösung auf, aber nicht die Gründe, wieso Sie diese benötigen. Warum muss die Lösung skalierbar sein, und warum brauchen Sie die Docker-Unterstützung? Mithilfe dieser Begründung können Sie in Zukunft besser entscheiden, ob sich diese Umstände geändert haben und inzwischen auch eine weniger skalierbare Lösung oder eine Lösung ohne Docker infrage kommt. Die von Nygard empfohlene Struktur „Kontext – Entscheidung – Konsequenzen“ hilft mir persönlich dabei, mich auf die Problembeschreibung zu konzentrieren.
Wie hält man Dokumentation aktuell?
Eine der häufigsten Fragen, die im Zusammenhang mit Dokumentation gestellt werden, ist: Wie halte ich sie auf dem aktuellen Stand? Die kurze Antwort ist leider: wahrscheinlich gar nicht – zumindest nicht zu 100 Prozent. Letzten Endes wird alles, was zum Ausführen der Software nicht nötig ist, früher oder später veraltet sein. Daher sind ausführbare Arten von Dokumentation wichtige Grundlagen, wie z.B. lesbarer, „selbst-erklärender“ Code, Tests und Skripte. Die hier bisher beschriebenen Techniken dienen dann als Ergänzung.Im Folgenden möchte ich einige Prinzipien vorstellen, mit denen ich versuche, die abstraktere, nicht ausführbare Dokumentation so aktuell wie möglich zu halten.
Nur das Nötigste erstellen
So wenig Dokumentation wie möglich zu haben, ist auf lange Sicht der beste Schutz vor veralteter Dokumentation. Je mehr Details Sie hinzufügen, desto höher ist die Wahrscheinlichkeit, dass Sie sie bald aktualisieren müssen. Überlegen Sie auch hier, welchen Nutzen ein dokumentiertes Element oder ein Detail hat, und bedenken Sie dabei, dass Sie es pflegen müssen – genau wie jede einzelne Zeile des Codes, den Sie schreiben.Und scheuen Sie sich auch nicht, immer mal wieder Dokumentation wegzuschmeißen. Manche der oben beschriebenen Beispiele sind nur vorübergehend nützlich, und das kann auch valide sein.
Pflege in Teamrituale integrieren
Denken Sie darüber nach, wie Sie die Pflege der Dokumentation in Ihre Teamrituale einbeziehen können. Ein wöchentlicher „Developer Huddle“ (auch manchmal „Show-and-Tell“ genannt) kann hier helfen. In diesem Wochentermin bespricht das Team technische Themen und Fragen, die sich im Laufe der Woche ergeben haben. „Gibt es was zu dokumentieren?“ kann hier als Checkpoint auf der Agenda stehen.
Sie sollten außerdem die Rotation von Teammitgliedern nutzen, um die aktuelle Nützlichkeit und Verständlichkeit Ihrer Dokumentation zu überprüfen.
Sichtbarkeit
Dokumentation, die in den Tiefen Ihres Wikis verschwindet, und auf die Sie nur selten zugreifen, ist ganz bestimmt bald nicht mehr aktuell. Wenn hingegen etwas für alle sichtbar an der Wand hängt, oder in einer Readme-Datei steht, die von jedem neuen Teammitglied gelesen wird, dann werden veraltete Stellen häufiger entdeckt und korrigiert.
Kollaboration
Erstellen Sie Dokumentation kollaborativ im Team erstellen, damit jeder sich für sie verantwortlich fühlt. Dies führt zu gemeinsamer „Ownership“ der Dokumentation, was die Wahrscheinlichkeit erhöht, dass alle Teammitglieder ein Auge auf die Artefakte haben und sie bei Bedarf aktualisieren. Wenn nur eine Person im Team die Dokumentation erstellt, kommt diese Einzelkämpferin langfristig nicht allein hinterher.
Agilität + Dokumentation = <3
Schauen wir abschließend noch mal zurück zum Agilen Manifest: Ja, am Ende ist es allein der Code, die „funktionierende Software“, die die Wahrheit über den aktuellen Stand der Systeme widerspiegelt. Die beschriebenen „high level“ Dokumentationsformen dienen hauptsächlich als Navigationshilfe. Sie zeigen Einstiegspunkte auf und erklären den Umgang mit dem System.Besonderes Augenmerk sollten Sie deshalb auf das haben, was der Code nicht verraten kann: Historie und Kontext. „Selbsterklärender“ Code hilft Ihnen nicht dabei, vergangene Entscheidungen zu überdenken oder zu verstehen, wieso etwas auf eine bestimmte Art implementiert wurde. Das Minimum sollte also sein, wichtige Entscheidungen zu dokumentieren. Auch eine gute Pflege Ihrer Commit-Messages mit Begründungen für kleine Design-Entscheidungen kann hier helfen.
Ich hoffe meine Beispiele haben auch gezeigt, dass das Erstellen und Pflegen von Dokumentation auch für einige andere der agilen Prinzipien ausschlaggebend sein kann, z. B. „Einfachheit“, „Fachexperten und Entwickler müssen täglich zusammenarbeiten“, „Augenmerk auf technische Exzellenz und gutes Design“ oder „In regelmäßigen Abständen reflektiert das Team, wie es effektiver werden kann“.
Wenn Sie dazu neigen, viel Dokumentation zu erstellen, und Sie „Waste“ reduzieren wollen: Priorisieren Sie, indem Sie sich auf den Mehrwert und Nutzen der Dokumentation konzentrieren. Beobachten Sie auch, welche Dokumentation Sie am Ende wirklich verwenden, und welche Sie nie wieder anschauen. Scheuen Sie sich nicht davor, Dinge zu löschen.
Wenn Sie eher sehr wenig Dokumentation erstellen: Überlegen Sie noch einmal, ob Ihnen einige der hier beschriebenen Mehrwerte fehlen, und welche Arten der Dokumentation Ihrem Team helfen würden, effektiver zu arbeiten.
Hinweis: Die in diesem Artikel geäußerten Aussagen und Meinungen sind die der Autor:innen und spiegeln nicht zwingend die Position von Thoughtworks wider.