„Funktionierende Software ist wichtiger als umfassende Dokumentation“ – so lautet eines der vier Werte-Statements des Manifests für Agile Softwareentwicklung. Vielleicht halten Sie ja auch Dokumentation für unnötigen Aufwand, weil sie direkt nach ihrer Erstellung schon veraltet ist? Oder sind Sie der Meinung, dass Ihr Code selbsterklärend ist, und dass es außer angestaubten, veralteten UML-Diagrammen eh keine hilfreichen Möglichkeiten gibt? Dieser Artikel beschreibt vier Ziele von Dokumentation, die mir beim Arbeiten in agilen Teams geholfen haben, die Kommunikation zu verbessern.
Das agile Manifest rät, uns mehr auf laufende Software zu fokussieren als auf Dokumentation. Dabei hat es aber noch eine Fußnote zu dem bewusst gewählten Muster von „A mehr als B“: „Obwohl wir die Werte auf der rechten Seite wichtig finden, schätzen wir die Werte auf der linken Seite höher ein.“ Auch wenn Dokumentation also durchaus ihren Wert hat, soll funktionierende Software mehr geschätzt werden. Und wir wollen funktionierende Software definitiv mehr schätzen als umfassende Dokumentation.
Wie „umfassend“ sollte Dokumentation also dann sein? Die Antwort ist, wie so häufig in der Softwareentwicklung: Es kommt darauf an. Leider gibt es keine feste Liste an Regeln, welche Formen von Dokumentation generell helfen, und welche generell Verschwendung sind. Um das richtige Maß für eine Tätigkeit zu finden hilft es aber immer, sich auf den jeweiligen Mehrwert zu konzentrieren. Man überlegt sich, warum man etwas dokumentieren will, wägt dann den Aufwand gegenüber dem Nutzen ab und priorisiert entsprechend.
Dieser zweiteilige Artikel beschreibt vier Nutzen von Dokumentation, die mir insbesondere dabei geholfen haben, die Kommunikation in einem agilen Team zu verbessern. Aus dem weiten Feld der Software-Dokumentation liegt der Fokus also in diesem Text darauf, wie Entwickler mithilfe relativ abstrakter Dokumentation sowohl im Team als auch mit direkten Stakeholdern besser kommunizieren können. Die dazu vorgestellten Beispiele sind Ergänzungen zu der Dokumentation, die durch gut lesbaren Code, Skripte und Tests ohnehin schon in Teams vorhanden sein sollte.
Wenn Sie Ihre Annahmen zum gemeinsamen Verständnis auf den Prüfstand stellen möchten, lassen Sie doch einmal jedes Teammitglied über ihr jeweiliges Verständnis in einem kleinen Workshop berichten. Teilen Sie Ihr Team in Gruppen auf, lassen Sie jede Gruppe ihre Sicht der Architektur ausarbeiten und anschließend gegenseitig vorstellen. So werden Missverständnisse aufgedeckt und Wissen ausgetauscht. Außerdem entsteht in der Übung ein gemeinsam erarbeitetes Übersichtsbild, das bei zukünftigen Diskussionen weiterentwickelt, und beim Einstieg neuer Teammitglieder verwendet werden kann.
Unabhängig davon, was am Ende an der Wand landet, eine selbst auferlegte Platzbeschränkung hat sich für mich als sehr hilfreich erwiesen. Bei einem Team, das physisch tatsächlich zusammensitzt, könnte diese Beschränkung beispielsweise sechs oder acht Blatt A4 Papier sein. Dann halten Sie in diesem Bereich alles fest, was Ihrer Ansicht nach jeder im Team über den Stand Ihres Systems wissen sollte. Die Platzbeschränkung ist deshalb nützlich, weil wir neben unserer täglichen Arbeit in der Regel ohnehin nur eine begrenzte Zahl von Konzepten schnell abrufbar halten können. Ermitteln Sie das Wesentliche, mit dem Sie effizient gemeinsam auf Ihre Ziele hinarbeiten können. Doppelt so viel Platz an der Wand zu reservieren, nur weil Sie an einem sehr großen System arbeiten, würde diesen Fokus nur verwässern.
Das Format einer „Infografik“, also einer Visualisierung mit relativ hohem Textanteil, ist bei dieser Art der Dokumentation besonders hilfreich. Als Beispiel möchte ich hier ein Team bringen, das eine Offline-First-Webanwendung baute. In dieser Architektur hatten wir Module für Datensynchronisierung, Datenmodell-Migrationen und Datenkonflikte zwischen Clients und Server – alles intrinsisch komplexe Konzepte. Diese Dinge wurden ganz am Anfang implementiert und im Laufe der weiteren Entwicklung nur selten verändert. Mithilfe von Infografiken konnten wir diese Konzepte prägnant beschreiben, ohne die Dinge zu sehr als reine Visualisierung zu vereinfachen und die Komplexität zu verbergen. Bei dieser recht detaillierten Mischung aus Grafik und Text kann die Leserin sich Zeit nehmen, um wirklich zu begreifen was passiert. Sie unterscheiden sich dadurch von den oben beschriebenen Übersichtsdiagrammen, die normalerweise einem schnellen, groben Überblick dienen.
Das agile Manifest rät, uns mehr auf laufende Software zu fokussieren als auf Dokumentation. Dabei hat es aber noch eine Fußnote zu dem bewusst gewählten Muster von „A mehr als B“: „Obwohl wir die Werte auf der rechten Seite wichtig finden, schätzen wir die Werte auf der linken Seite höher ein.“ Auch wenn Dokumentation also durchaus ihren Wert hat, soll funktionierende Software mehr geschätzt werden. Und wir wollen funktionierende Software definitiv mehr schätzen als umfassende Dokumentation.
Wie „umfassend“ sollte Dokumentation also dann sein? Die Antwort ist, wie so häufig in der Softwareentwicklung: Es kommt darauf an. Leider gibt es keine feste Liste an Regeln, welche Formen von Dokumentation generell helfen, und welche generell Verschwendung sind. Um das richtige Maß für eine Tätigkeit zu finden hilft es aber immer, sich auf den jeweiligen Mehrwert zu konzentrieren. Man überlegt sich, warum man etwas dokumentieren will, wägt dann den Aufwand gegenüber dem Nutzen ab und priorisiert entsprechend.
Dieser zweiteilige Artikel beschreibt vier Nutzen von Dokumentation, die mir insbesondere dabei geholfen haben, die Kommunikation in einem agilen Team zu verbessern. Aus dem weiten Feld der Software-Dokumentation liegt der Fokus also in diesem Text darauf, wie Entwickler mithilfe relativ abstrakter Dokumentation sowohl im Team als auch mit direkten Stakeholdern besser kommunizieren können. Die dazu vorgestellten Beispiele sind Ergänzungen zu der Dokumentation, die durch gut lesbaren Code, Skripte und Tests ohnehin schon in Teams vorhanden sein sollte.
1. Gemeinsames Verständnis schaffen
Ich ertappe mich als Lead Developer in einem Team oft dabei, dass ich einfach davon ausgehe, dass jeder im Team dasselbe Verständnis von dem hat, was wir gerade tun. Die anderen haben doch bestimmt das gleiche Bild der Architektur in ihrem Kopf wie ich, schließlich reden wir fast täglich darüber - ? Wenn das wirklich der Fall wäre, müssten wir eigentlich keine scheinbar offensichtlichen Dinge aufschreiben oder an die Wand heften. Dieser Illusion eines gemeinsamen Verständnisses im Team unterliegen meiner Erfahrung nach vor allem erfahrene EntwicklerInnen.
Architektur „Show-and-Tell“
Wenn Sie Ihre Annahmen zum gemeinsamen Verständnis auf den Prüfstand stellen möchten, lassen Sie doch einmal jedes Teammitglied über ihr jeweiliges Verständnis in einem kleinen Workshop berichten. Teilen Sie Ihr Team in Gruppen auf, lassen Sie jede Gruppe ihre Sicht der Architektur ausarbeiten und anschließend gegenseitig vorstellen. So werden Missverständnisse aufgedeckt und Wissen ausgetauscht. Außerdem entsteht in der Übung ein gemeinsam erarbeitetes Übersichtsbild, das bei zukünftigen Diskussionen weiterentwickelt, und beim Einstieg neuer Teammitglieder verwendet werden kann.
Abbildung 1: Gemeinsames Verständnis schaffen durch Visualisierung
Im Arbeitsbereich des Teams lasse ich immer gerne etwas Raum für eine „Wall of Common Understanding“, an der Übersichtsbilder der Kernkonzepte der Architektur hängen. Der Inhalt dieser Wand ist abhängig von der jeweiligen Software – normalerweise gibt es eine Systemübersicht mit externen Abhängigkeiten, häufig auch eine Übersicht über Komponenten und Technologie-Stacks. Wenn das Setup der Umgebungen komplex ist, hängt das vielleicht auch dort, bei einer sehr einfachen Umgebung muss man dafür eher keinen Platz verschwenden.
Abbildung 2: Beispiel für eine „Wall of Common Understanding“
Unabhängig davon, was am Ende an der Wand landet, eine selbst auferlegte Platzbeschränkung hat sich für mich als sehr hilfreich erwiesen. Bei einem Team, das physisch tatsächlich zusammensitzt, könnte diese Beschränkung beispielsweise sechs oder acht Blatt A4 Papier sein. Dann halten Sie in diesem Bereich alles fest, was Ihrer Ansicht nach jeder im Team über den Stand Ihres Systems wissen sollte. Die Platzbeschränkung ist deshalb nützlich, weil wir neben unserer täglichen Arbeit in der Regel ohnehin nur eine begrenzte Zahl von Konzepten schnell abrufbar halten können. Ermitteln Sie das Wesentliche, mit dem Sie effizient gemeinsam auf Ihre Ziele hinarbeiten können. Doppelt so viel Platz an der Wand zu reservieren, nur weil Sie an einem sehr großen System arbeiten, würde diesen Fokus nur verwässern.
Geeignete Kandidaten für die Wand finden
- Was erklären Sie neuen Teammitgliedern immer in deren erster Woche?
- Was müssen Sie Stakeholdern oft erklären, damit diese einen groben Überblick über das System erhalten?
- Was ändert sich nur selten?
2. Komplexes sichtbar machen und verstehen
Als Entwickler streben wir stets nach Einfachheit unserer Software und einem leicht lesbaren, „selbsterklärenden“ Code. Dennoch entstehen am Ende immer Teile der Software, die nicht trivial, aber kritisch sind. Bei diesen Komponenten ist Dokumentation besonders wichtig. Damit können wir diesen Code nicht nur einfacher lesen und erklären, sondern auch besser bewerten, ob die Implementierung sinnvoll ist, und unbeabsichtigte Komplexität aufdecken.
Infografiken
Das Format einer „Infografik“, also einer Visualisierung mit relativ hohem Textanteil, ist bei dieser Art der Dokumentation besonders hilfreich. Als Beispiel möchte ich hier ein Team bringen, das eine Offline-First-Webanwendung baute. In dieser Architektur hatten wir Module für Datensynchronisierung, Datenmodell-Migrationen und Datenkonflikte zwischen Clients und Server – alles intrinsisch komplexe Konzepte. Diese Dinge wurden ganz am Anfang implementiert und im Laufe der weiteren Entwicklung nur selten verändert. Mithilfe von Infografiken konnten wir diese Konzepte prägnant beschreiben, ohne die Dinge zu sehr als reine Visualisierung zu vereinfachen und die Komplexität zu verbergen. Bei dieser recht detaillierten Mischung aus Grafik und Text kann die Leserin sich Zeit nehmen, um wirklich zu begreifen was passiert. Sie unterscheiden sich dadurch von den oben beschriebenen Übersichtsdiagrammen, die normalerweise einem schnellen, groben Überblick dienen.
Figure 3: Beispiel einer Infografik
Geeignete Kandidaten für Infografiken finden
- Komplizierte Dinge, mit denen Sie nicht oft arbeiten und an deren Funktionsweise Sie sich dann nur schwer erinnern können. Je kritischer die Komponente für die Anwendung ist, desto wichtiger ist es, sie zu dokumentieren.
- Sie haben gerade einen neuen Teil eines Systems entwickelt und möchten sichergehen, dass das Design nicht zu kompliziert ist? Wenn Sie keine verständliche Infografik erstellen können, ist das vielleicht ein Zeichen dafür, dass es tatsächlich noch einen besseren Weg geben könnte. Durch den Denkprozess beim Erstellen der Dokumentation kann das Design damit noch besser werden.
Papier-Baukasten
Um das häufige Erklären eines nicht trivialen Teils der Architektur zu vereinfachen, erstelle ich manchmal einen Baukasten aus Karteikarten und anderen Papierhilfen. Damit lässt sich ein Bild Schritt für Schritt aufbauen, im Rahmen eines Gesprächs. Unser Baukasten „Explain our data model“ enthielt beispielsweise Bildschirmskizzen, Karten für Daten-Entitäten, sowie eine Reihe von Karten mit unseren Datenimportjobs. So konnten wir Außenstehenden nicht nur das Datenmodell erklären, sondern auch darüber sprechen, woher die Daten stammten und wofür sie verwendet wurden.
Geeignete Kandidaten für Papier-Baukasten finden
- Teile der Software mit umfangreicher Historie und vielen Informationen „zwischen den Zeilen“, die sich schwer schriftlich festhalten lassen.
- Dinge, über die ich mit einer Person lieber eine Unterhaltung führe, anstatt sie einen Wiki-Eintrag lesen zu lassen.
- Umfangreiche Konzepte, bei denen eine Schritt-für-Schritt-Erklärung das Verständnis erleichtert.
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.