Warum Sie Ihre Softwarearchitektur jetzt dokumentieren werden

Für den Podcast zur OOP-Konferenz interviewte ich David Parnas. David ist einer der Ur-Väter des Software Engineering, z.B. ist er der Entdecker des Geheimnisprinzips (auch bekannt als information hiding oder Kapselung). Er hat auch als einer der ersten das Phänomen der Kopplung in der Softwarearchitektur systematisch untersucht und beschrieben (Sie kennen sicher die vier Arten der Kopplung nach Parnas, richtig?).

Das Interview mit David Parnas

Im Interview ging es um Dokumentation. Ich fragte David, warum Teams ihre Architektur so ungern dokumentieren.

David: „Es ist nicht so, dass sie es nicht mögen. Es liegt daran, dass sie nicht wissen, wie. Deshalb schreiben sie eine Menge vager Wörter, z.B. dies nutzt das Blackboard-Modell. Blackboard bedeutet unterschiedliche Dinge für unterschiedliche Menschen. Es sagt dir noch nicht exakt, wie du an ein Blackboard schreibst, wie du davon liest, was die Notation der Dinge auf dem Blackboard bedeutet, usw. Sie benutzen sehr vage Beschreibungen. Und das ist noch nicht einmal der Anfang der Dokumentation von Softwarearchitektur.“

David fährt fort: „Leute stellen dann fest, dass nicht alle anderen die Dokumente in derselben Weise verstehen! … Vor langer Zeit bat mich die U.S. Navy, ein Projekt zu reviewen, das langsam war. Sie wollten wissen, ob sie es fertigstellen oder besser abbrechen sollten. Ich fuhr dafür nach Kalifornien. Die Leute waren sehr beschäftigt, denn sie waren spät dran. Sie mussten ihre Deadline erreichen, deshalb erlaubten sie mir nicht, mit der ganzen Gruppe auf einmal zu sprechen, und ich bekam stattdessen nur eine halbe Stunde mit jedem.

Jede Person, die in mein Zimmer kam, bat ich darum, mir zu zeigen, was die Architektur war. Und sie zeichnete ein Bild an die Tafel. Dann sprachen wir eine Weile darüber, dann ging eine Person raus, jemand anders kam herein und warf einen Blick auf das Bild. Und das erste, was jeder sagte, war: „Das ist ein interessantes Bild, aber das ist nicht unsere Architektur!“ Danach fing jeder an, Teile des Bildes auszuwischen und zu ändern, ein neues Diagramm, manchmal ließ er ein Teil des alten Diagramms stehen, und die Diskussion zeigte, dass er das Bild anders interpretierte als die Person vorher.

Alle dachten, sie hätten eine Architektur. Aber sie hatten nicht dieselbe Architektur in ihren Köpfen. Als ich realisierte, was hier passierte, bat ich um eine Polaroidkamera, um die Bilder aufzunehmen (daran kannst du sehen, wie lange das schon her ist)…“

Matthias: „Also hatte jeder sein eigenes Bild von derselben Sache. Haben die vorher nicht genug miteinander gesprochen?“

David: „Doch, sie sprachen miteinander, aber nur sehr vage. Es ist sehr einfach, eine Blackbox zu zeichnen, mit einem Pfeil, der hereinkommt und einem, der hinausgeht… Ich machte das in meinen Kursen als Experiment: Ich zeichnete ein Diagramm und bat jeden aufzuschreiben, was damit gemeint wäre.  Und dann lasen alle vor. Und alle hatten etwas Unterschiedliches.

Ungefähr 10% hatten gesagt, sie wüssten noch nicht genug, doch 90% hatten etwas aufgeschrieben, von dem sie sehr sicher waren, was es bedeutete. Und keiner hatte dasselbe verstanden.“

Matthias: „Es ist ziemlich schwierig, Leute dazu zu bringen, sich auf eine Architektur zu einigen.“

David: „Naja … Du kannst Dich halt nicht auf eine Architektur einigen, wenn Du sie nicht aufschreiben kannst. … Es ist ziemlich offensichtlich, dass Leute ein Dokument brauchen, auf das sie sich einigen können oder über das sie sich streiten können. Aber sie wissen einfach nicht, wie sie dafür die wirklich kritischen Details aufschreiben sollen.“

Soweit der Auszug aus dem Interview, das Sie im Podcast ausführlich anhören können.

Architekturkommunikation braucht eine Stütze

Der Schlüsselsatz in diesem Abschnitt war für mich dieser:

Du kannst Dich nicht auf eine Architektur einigen, wenn Du sie nicht aufschreiben kannst (David Parnas)

Architektur aufzuschreiben ist eminent wichtig, damit Leute, die im selben Projekt oder an demselben Produkt arbeiten, auch wirklich dasselbe System erschaffen. Über ein Dokument kann man streiten und sich einigen. Wenn man es nicht hat, bleiben Fragen offen und Raum für Interpretation.

Also müssen Softwarearchitekten lernen, ihre Architektur aufzuschreiben, mit anderen Menschen darüber zu kommunizieren, Feedback einzuholen und dies einzuarbeiten. In meinem Advanced Level Workshop Softwarearchitektur dokumentieren zeige ich, wie es geht. Sie können nach Köln kommen, dort findet es statt, dort üben wir  es gemeinsam, zwei Tage lang, intensiv.

Warum Doku für Softwarearchitektur cool ist

Architekturdokumentation hat sechs wichtige Vorteile:

1. Sie erleichtert die Einarbeitung neuer Teammitglieder. Die alten sind in der Regel beschäftigt. Die Neuen können die Doku lesen und finden dort die meisten Fragen beantwortet.
2. Die Doku beantwortet die Fragen nach dem „Warum“. Warum ist das System oder diese Komponente so? Das Was (z.B. Daten) und das Wie (z.B. Algorithmen und ausführbare Tests) stehen ja im Code – kein Problem. Doch die Entscheidungen, die dazu geführt haben, eben nicht! Und die Begründungen schon gar nicht. Kein anderes Artefakt außer Architektur-Doku leistet das.
3. Die Doku macht Architektur bewertbar. In regelmäßigen Abständen können Teams ein Review auf ihre Architektur machen und fragen: Ist sie angemessen? Leistet sie, was sie soll? Das geht nicht, wenn man keine einheitliche Vorstellung hat, was die Architektur ist.
4. Die Doku hilft, Fehler zu vermeiden. Beispiel: Eine Komponente wird um Dinge erweitert, die nicht ihrer Verantwortung entsprechen. Sie bläht sich auf und wird unwartbar. Das können Sie verhindern, wenn jeder durch die Architektur-Doku weiß, was die Verantwortung dieser Komponente ist und wie sie konzeptionell gedacht war. Aus dem Code gehen diese Prinzipien nicht hervor, immer nur die Details.
5. Die Doku hilft beim Denken. Wenn sich etwas denken aber nicht verständlich aufschreiben lässt, ist es wahrscheinlich zu kompliziert und muss vereinfacht werden. Sie können mit Hilfe moderner Doku-Methoden die Struktur der Doku identisch zur Struktur des Entwurfs gestalten. So sparen Sie Zeit und Arbeit, indem Sie dokumentieren, während Sie entwerfen, nicht davor und nicht danach.
6. Die Doku unterstützt die Kommunikation im Projekt: Sie brauchen nicht immer alles erneut an die Tafel zu malen. Sie lernen aus dem Feedback, das andere Ihnen zu Ihrer Doku geben, was die beste Art und Weise ist, eine bestimmte Stelle im Entwurf zu erklären und wo die schwierigsten Stellen liegen. Gruppen kommen in der Kommunikation schneller weiter, wenn sie ein soziales Objekt wie die Doku dazu nutzen können.

Lernen und Üben

Mittlerweile gibt es tonnenweise Erfahrungswissen darüber, wie Sie gute Architekturdokumentation erstellen und pflegen können. Warum also das Rad neu erfinden? Warum erst durch Versuch und Irrtum über Monate ermitteln, wie Sie Ihre Architektur aufschreiben sollten? Kürzen Sie den Weg ab und nutzen Sie meine lange Erfahrung dazu.

Am besten, Sie kommen in meinen Fortgeschrittenen-Workshop Softwarearchitektur dokumentieren, dort zeige ich, wie es geht. Wir üben es gemeinsam, zwei Tage lang, intensiv. Danach wissen Sie exakt, wie man dokumentiert und darüber kommuniziert, und Sie bekommen für den Workshop sogar noch 20 Credit Points für den iSAQB Certified Professional for Software Architecture, Advanced Level (CPSA-A).

Hier geht es zur Workshop-Seite. Dort stehen alle Details zur Anmeldung, zum Termin, zum Inhalt. Und auch, was es kostet.

Ich freue mich darauf, Sie im Workshop zu begrüßen. Es wird richtig spannend, intensiv, und es wird Spaß machen. (Und gutes Essen und Trinken gibt es auch, ist klar!). Also auf nach Köln.