Sparsame Dokumentation

Dr. Gernot Starke

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.

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)

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:

• Abschnitt 1.1 und 1.2: Anforderungsübersicht (2–3 Sätze) plus die 3–5 wichtigsten Qualitätsanforderungen (z.B. als Qualitätsszenarien)
• Abschnitt 3: Kontextabgrenzung, ein Diagramm mit Erläuterung der wichtigsten externen Schnittstellen
• Abschnitt 4: Wichtigste Lösungsansätze, Kernideen, z.B. Technologieauswahl.
• Abschnitt 5.1: Bausteinsicht, Ebene 1: Top-Level-Systemzerlegung. Diagramm mit Erläuterung
• Abschnitt 8: Wichtige übergreifende Konzepte: Wie werden die wichtigsten Probleme innerhalb des Systems gelöst.

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:

• Wichtige Stakeholder dokumentiert haben wollen oder unbedingt benötigen
• Sie oder Ihr Team auch in Zukunft aktuell halten können

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

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.

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:

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.

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:

Zusammenfassend empfehle ich Folgendes:

• Diagramme brauchen eine Legende. Sie können darauf verzichten, wenn Sie eine standardisierte Notation wie UML verwenden, aber ich schlage vor, zur Sicherheit immer eine Legende zu verwenden.
• Ergänzen Sie Ihre Diagramme mit einer tabellarischen Erklärung der Elemente im Diagramm. Erläutern Sie zumindest die wichtigsten Elemente, seien es Kästen oder Linien oder beides.
• Vermeiden Sie es, viele verschiedene Symbole, Stile oder Farben zu mischen. Verständlichkeit und Einheitlichkeit sind wichtiger als “bunt”.
• Dennoch können und sollten auch technische Diagramme visuell ansprechend sein: Seien Sie großzügig mit freien Flächen (whitespace), achten Sie auf visuelle Konsistenz, Bündigkeit und beschränken Sie Ihre Diagramme auf 10–15 Elemente.

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

• Eine Begriffsklärung What is Software Architecture?
• arc42, ausführliche Dokumentation und viele Tipps unter https://docs.arc42.org und https://faq.arc42.org.
• Mein Video über sparsame Dokumentation