Avatar of Gernot Starke

Dokumentation ist ein Liebesbrief an Dein zukünftiges Ich.

Damian ConwayPerl Best Practices, p.132, O'Reilly

Randbemerkung: Für ein gemeinsames Verständnis des Begriffs „Softwarearchitektur“ siehe die Erläuterung von Softwarearchitektur zum Thema. In diesem Artikel beziehe ich mich oft auf das (quelloffene und kostenlose) arc42. Vielleicht möchten Sie auch die kurze Einführung lesen.

Warum das Ganze?

Bevor wir in die good practices einsteigen, kurz ein paar Gründe, warum sich Entwicklungsteams um die technische Dokumentation kümmern sollten, insbesondere um die Architekturdokumentation.

Grund 1: Vergessen

Sie, bzw. das Entwicklungsteam, werden wichtige Entscheidungen, Überlegungen und Argumente vergessen.

Eine geeignete Dokumentation hilft, sich an wesentliche Dinge zu erinnern. Neben gut geschriebenem Code ist Dokumentation eine Grundlage für die längerfristige Pflege (aka Wartung) Ihres Systems.

Grund 2: Neue Personen

Von Zeit zu Zeit werden neue Beteiligte (aka Stakeholder) ein berechtigtes Interesse an Ihrem System, dessen Architektur, dem Innenleben und/oder dem Betrieb zeigen. Da hilft angemessene Architekturdokumentation und minimiert den Zeitaufwand für das Verständnis von Architekturentscheidungen.

Grund 3: Niemand mag Müllhalden

In meinen mehr als 30 Jahren als praktizierender Softwerker habe ich zahlreiche Unternehmen erlebt, in denen technische Dokumentation im Laufe der Zeit zu einem unstrukturierten Chaos verkommen ist: Netzlaufwerke, die buchstäblich Dutzende verschiedener Dokumente unter dem Begriff »technische Dokumentation« enthielten – aber ohne roten Faden oder irgendeine Navigationshilfe. (Pseudo-) Versionsnummern, an Dateinamen angehängt. Dokumente, deren Änderungsdatum bereits 5–10 Jahre zurück lag, und in denen völlig unbekannte Begriffe verwendet wurden. Ich vermute, Sie kennen das.

Oft resultierte die Müllhalde aus gravierenden Missverständnissen über grundlegende Dokumentationsprinzipien.

Grund 4: Zeitfresser

Wie oben erläutert, kann eine ungesteuerte und unstrukturierte Dokumentation in einem übermäßig großen Haufen nutzloser Dokumente enden, die insgesamt einen negativen Nutzen aufweisen:

  1. Für Leser:innen dauert es zu lange, Informationen zu finden
  2. Sie können sich auf die Korrektheit und Aktualität nicht verlassen
  3. Für das Entwicklungsteam ist es fast unmöglich, die Dokumentation aktuell zu halten

Dokumentieren Sie so kompakt wie möglich.

Sorgen Sie für schlanke und effektive Dokumentation mit angemessenem Detailgrad.

Grund 5: Keine Doku ist keine Lösung

Der Quellcode enthält die ultimative Wahrheit jeder Software – aber es fehlen die Argumente und Gründe für Entscheidungen. Es ist schwierig bis unmöglich, sich anhand von atomaren Details einen Überblick zu verschaffen (mit Ausnahme von Hello-World-ähnlichen Systemen).

Dokumentation hilft an manchen Stellen, das Risiko bei Änderungen und Erweiterungen zu verringern.

Sieben Tipps für sparsame Dokumentation

Meine Tipps basieren auf [arc42] (https://arc42.org), dem freien und quelloffenen Strukturvorschlag (auch bekannt als template) für die Dokumentation von Softwarearchitekturen (Hinweis: Ich trage Mitschuld an arc42, und bin dort aktiver Committer). arc42 gibt es seit 2005 und wird von zahlreichen Organisationen weltweit verwendet. In diesem Artikel finden Sie eine kurze Einführung.

Die arc42-Dokumentation enthält Dutzende Tipps und Tricks für schlanke Dokumentation.

1. Klären, was Leute wirklich brauchen

Die alternative Überschrift lautet: Finden Sie heraus, was Sie alles weglassen können.

Bevor Sie mit Dokumentation anfangen, sollten Sie mit Ihren relevanten Stakeholdern (sprich: allen wichtigen Personen) klären, welche Fragen Ihre Dokumentation denn aktuell und zukünftig beantworten soll. Ein Template wie arc42 kann nämlich fast alle Fragen beantworten - viele davon werden für Ihr konkretes System jedoch gar nicht relevant sein. Die Chancen stehen meiner Erfahrung nach ziemlich gut, dass Sie diverse Teile des Templates getrost weglassen können, also eine Menge Doku-Arbeit von vornherein sparen können.

Zeigen Sie also Ihren Stakeholdern das arc42-Template und fragen, welche Teile davon sie (also die Stakeholder) wirklich brauchen, und zu welchem Zweck. Die Antworten darauf halten Sie in der Stakeholdertabelle (arc42 Abschnitt 1.3) fest :-) Das Entwicklungsteam gehört übrigens auch zu den wichtigen Stakeholdern.

Praktisch geht das ganz einfach: Zeigen Sie Ihren Stakeholdern die möglichen Themen auf (wie in der nachfolgenden Abbildung gezeigt) – und lassen sie dann die jeweils interessanten oder wichtigen Teile markieren. In der Abbildung unten habe ich fiktive Klebezettel dazu verwendet.

Fragen Sie, was Stakeholder konkret an Doku benötigen
Fragen Sie, was Stakeholder konkret an Doku benötigen

Für manche Systeme existieren rein formale oder organisatorische Gründe, dass bestimmte Informationen dokumentiert und aktuell gehalten werden müssen, beispielsweise vorgeschriebene Audits oder ähnliche Qualitätsprüfungen. In diesen Fälle ist der Aufwand für Dokumentation allerdings in Projekt- oder Entwicklungsplanung eingeplant. Sie sollten in solchen Fällen dennoch genau überlegen, wie sie die geforderten Informationen mit überschaubarem Aufwand produzieren und aktuell halten können.

2. Take five (oder: Fünf-aus-Zwölf)

Randbemerkung (hat nichts mit der Dokumentation zu tun, ist aber trotzdem gut zu wissen)

Take Five ist der Titel eines berühmten Jazz-Songs, komponiert von Paul Desmond. Hören oder schauen Sie mal rein:

Wenn Sie unter Zeit- oder Ressourcenknappheit arbeiten, ständig in Eile sind und nicht viel Zeit in die Dokumentation investieren können, dann wenden Sie die Fünf-aus-Zwölf-Regel an:

Beschränken Sie Ihre Dokumentation auf die folgenden fünf Teile von arc42:

Fünf wesentliche Bestandteile einer Architekturdokumentation
Fünf wesentliche Bestandteile einer Architekturdokumentation

Die Dokumentation zu arc42 enthält zahlreiche Tipps, wie Sie diese Themen dokumentieren können.

Anmerkung: Tipps 1 und 2 könnten sich gegenseitig widersprechen…

3. Auf Details verzichten

Zu viele Details sind der Feind der Wartbarkeit: Lassen Sie manche Details weg: Wenn Sie einige Details weglassen, verringert sich die Menge der Inhalte, die Sie in Zukunft aktuell halten müssen. Dokumentieren Sie deshalb nur Dinge, die:

Diesen Tipp können Sie einfach umsetzen, in dem Sie Abstraktionen statt Details verwenden. Die folgende Tabelle enthält einige Beispiele (Quelle)

statt … versuchen Sie dies …
alle externen Schnittstellen zu benennen/anzuzeigen Schnittstellen zu gruppieren, insbesondere wenn Sie explizite Kohäsionskriterien angeben können
eine bestimmte Versionsnummer angeben diese Versionsnummer weglassen oder einen Bereich wie „Version >2.1“ angeben
alle Kinder eines Elements anzeigen Kinder weglassen, nur das übergeordnete Element erwähnen
alle Abhängigkeiten zwischen zwei Elementen anzeigen nur eine (aggregierte) Abhängigkeit anzeigen (siehe unten für ein Beispiel)
Erläuterung von Schnittstellendetails wie Parameter nur die Schnittstelle benennen, Details weglassen

Sie erkennen das zugrunde liegende Prinzip: Das Weglassen von Details erleichtert Änderungen und macht Ihre Dokumentation robuster gegenüber (zumindest einigen) Änderungen der Anforderungen, des Codes oder der Infrastruktur.

4. Übersicht ist Ihr Freund

Leser:innen von Dokumentation sollten immer mit einer Übersicht beginnen können, und dann bedarfsgerecht „eintauchen“ können. Eine solche Übersicht liefert Kontext für nachfolgende Details. Ein Überblick, zum Beispiel über die statische Struktur von Subsystemen, Services oder Packages Ihres Systems, kann als Ausgangspunkt für das Verständnis des Codes selbst dienen.

Organisieren Sie daher Ihre Dokumentation top-down, also vom Überblick ausgehend zu mehr Details..

Ihre Dokumentation wird sicherlich einige technische Details enthalten, insbesondere wenn diese Voraussetzung für das Verständnis bestimmter Entscheidungen oder Konzepte sind. Stellen Sie sicher, dass Ihre Leser:innen den Kontext dieser Details verstehen können. Fügen Sie Verweise auf externe Dokumente für diejenigen hinzu, denen bestimmte Voraussetzungen fehlen.

In Bezug auf arc42: Ich persönlich halte die Übersicht über die Bausteine der Ebene 1 für eines der wichtigsten Artefakte jeder Dokumentation, da sie den Überblick über den gesamten Quellcode auf oberster Ebene bietet! Sehr oft brauchten Teams keine (oder nur sehr wenige) verfeinerte Diagramme, da die Übersicht (Ebene 1) ausreicht, um die Struktur des gesamten Systems zu verstehen.

5. Ersetze (einige) Diagramme durch Konzepte

Insbesondere in der Bausteinsicht besteht das Risiko von Redundanz: Manchmal werden Themen dort mehrfach visualisiert - insbesondere wenn unterschiedliche Autor:innen an der Dokumentation beteiligt waren.

Nehmen Sie folgendes Beispiel: In jedem der Bausteine A,B und D ist das Zusammenspiel zwischen Dispatcher, Worker und Store erklärt. Das ist in allen Fällen sicherlich sachlich korrekt, aber total redundant.

Zu viel Redundanz in der Bausteinsicht
Zu viel Redundanz in der Bausteinsicht

Geschickter wäre es, den prinzipiellen Aufbau dieser Komponenten als ein querschnittliches Konzept zu beschreiben – und in der Bausteinsicht dann nur noch die Anwendung dieses Konzeptes zu referenzieren. Einen Vorschlag dafür zeigt Fig. 4:

Querschnittliche Konzepte anwenden
Querschnittliche Konzepte anwenden

6. Erkläre Diagramme

Von wegen, ein Bild sagt mehr als 1000 Worte. Ein Bild kann erheblich verwirren, oder gar für Mißverständnis sorgen – falls beispielsweise darin mehrdeutige Begriffe enthalten sind, oder die Bedeutung von Elementen implizit (d. h. unklar) bleibt.

Ein erklärungsbedürftiges Beispieldiagramm
Ein erklärungsbedürftiges Beispieldiagramm

Ohne Erklärung kann dieses Diagramm sehr irreführend sein: Was ist ein „Reporter“? Ein Journalist? Eine Komponente, die einen Bericht erstellt, oder ein Dienst, der Berichte konsumiert?

Selbst mit der Legende bleibt unklar, was der ursprüngliche Autor (übrigens ich) mit den Kästchen und Pfeilen meinte. Eine Tabelle, die wichtige Elemente eines Diagramms erklärt, kann helfen, solche Unklarheiten zu beseitigen - sehen Sie selbst:

Element Verantwortung / Bedeutung Details
Checker führt die eigentliche Prüfung durch, verlässt sich auf die Status- und Fehlermeldungen des Parser org.aim42.hsc.core
Parser Open-Source-Bibliothek zum Parsen von HTML-Dateien org.jsoup
Suggester schlägt Lösungen für Probleme vor, die bei der Überprüfung gefunden werden org.aim42.hsc.core
Reporter erstellt einen formatierten HTML-Bericht über alle bei der Prüfung gefundenen Probleme org.aim42.hsc.core

Zusammenfassend empfehle ich Folgendes:

7. Verwende angemessene Werkzeuge

Konzentrieren Sie sich auf den Inhalt, reduzieren Sie den Zeitaufwand für die Einrichtung und Pflege Ihrer Tools. Automatisierung ist großartig, aber kein Wert an sich: Sie verbessert den Inhalt von Dokumentation nicht.

Bevorzugen Sie etablierte Tools, weil diese in der Regel einen geringeren Wartungs-, Pflege- und Supportaufwand verursachen. Ja, leider machen die oft auch weniger Spaß bei der Benutzung.

Sie brauchen Werkzeuge für Text, Tabellen und Diagramme. Es ist in Ordnung, mehrere verschiedene Tools zu verwenden, solange deren Ausgaben in einem einzigen Dokument, Verzeichnis oder Repository zusammenlaufen.

Für sparsame und schlanke Dokumentation nutzen Sie Werkzeuge mit niedriger Einstiegshürde, damit sich alle Autor:innen sofort auf den Inhalt konzentrieren können.

High-End-Tools, beispielsweise UML-Modellierungswerkzeuge, benötigen erhebliche Einarbeitung. Darüber hinaus erfordert die Verwendung solcher Werkzeuge einen hohen Wartungs- und Supportaufwand. Verwenden Sie diese Kategorie von Tools nur, wenn Sie die fortschrittenen Features auch wirklich benötigen.

Mein persönliches Minimal-Setup besteht aus einem Markdown- oder AsciiDoc Editor zusammen mit draw.io (das vor kurzer Zeit in diagrams.net umbenannt wurde).

Quellen

An dieser Stelle möchten wir Dir gerne ein YouTube Video anzeigen. Um es zu sehen, musst Du dem Laden von Fremdinhalten von youtube.com zustimmen.

Fazit

(Architektur-)Dokumentation geht auch schlank und schmerzfrei. Klären Sie mit Ihren Stakeholdern deren genaue Bedürfnisse, damit Sie auf keinen Fall zuviel dokumentieren. Schreiben und skizzieren Sie ruhig mal etwas abstrakter, nach dem Motto Mut zur Lücke. Erklären Sie in einer kleinen Tabelle die wesentlichen Elemente von Diagrammen, das bieter einerseits Übersicht und vermeidet andererseits implizite Annahmen. Coole, aber exotische Tools bergen (neben Chancen) auch Risiken.

Last not least: möge die Macht effektiver Dokumentation mit Ihnen sein.

Sprechen Sie mit uns