„Frag das Team!“ für Architekturdokumentation?

Ich platze vor Neid. Scrum-Berater haben eine universelle Antwort auf alle Fragen, etwa die eines Scrum-Masters in Ausbildung (SIP), parat. Insbesondere, wenn es konkret wird, und die Fragen mit „Wie“ und „Wann“ eingeleitet werden, lautet die Antwort stets „Frag das Team!“. Oft kommt sie prompt als wäre es das klarste von der Welt. Ich stelle ich mir den kleinen Yoda vor, wenn ich sie höre: „Das Team fragen Du musst.“. Und wenn Sie mir nicht glauben: Hier ist ein ein schönes Scrum FAQ online, das viele unterschiedliche Fragen, aber keine unterschiedliche Antworten parat hat. Es ist stattdessen eine Gruppenarbeit: „The questions are intended to be read and answered as a team.“ Toll.

In einem Kundenworkshop zu Architekturdokumentation habe ich mich letztens dabei ertappt, eine ähnliche Strategie zu verfolgen wie die Scrum-Berater. Ich hatte auch eine universelle Antwort benutzt, die verblüffend oft auf in Diskussionen aufgeworfene Fragen passte. Sie lautete „Wenn es den Leser interessiert.“ Mitunter wird so auch gleich die Schwäche in der Frage aufgedeckt, dass gar nicht genau klar ist, wer der Leser eigentlich ist. Eine 42 für Architekturdokumentation? (vgl. 42 bei Wikipedia)

7 Regeln für angemessene Dokumentation

Tatsächlich handelt es sich bei dieser Antwort übrigens um eine einfache Anwendung der 7 Regeln für angemessene Dokumentation. Sie werden im Buch Documenting Software Architectures vorgestellt, sind aber universell für Dokumentation gedacht. Hier sind sie komplett:

1. Schreibe Dokumentation aus Sicht des Lesers
2. Vermeide unnötige Wiederholungen
3. Vermeide Mehrdeutigkeit
4. Verwende eine Standardstrukturierung
5. Halte Begründungen fest
6. Halte Dokumentation aktuell, aber nicht zu aktuell
7. Überprüfe Dokumentation auf Gebrauchstauglichkeit

„Wenn es den Leser interessiert“ ist eine Anwendung von Regel 1, und diese ist in der Praxis übrigens gar nicht so leicht zu befolgen, wie es auf den ersten Blick scheint. Das gilt für viele dieser Regeln.

Eine Architekturbeschreibung auf n Seiten, n < 30

Meiner Erfahrung nach wünschen sich viele Vorhaben ihre Architektur beschrieben in einem einzelnen Dokument, das vom Umfang her überschaubar ist. Die Seitenzahl sollte z.B. 30 DIN-A4-Seiten nicht überschreiten. Jeder Projektbeteiligte sollte das Dokument lesen (idealerweise von vorne nach hinten) und auch verstehen können; es manifestiert das gemeinsame Verständnis von der Softwarearchitektur. Dabei handelt es sich um genau so eine Art von Dokument, wie es entstehen soll, wenn Sie eine Vorlage wie z.B. arc42 benutzen (siehe Regel 4). Dass es sich dabei um eine verlockende Sache handelt, ist unstrittig.  Gleichzeitig ist die Erstellung aber schwierig, denn es drohen eine Reihe Fallen. Der Grund sind die besonderen Anforderungen:

• Die Zielgruppe ist heterogen
• Die Arbeitsergebnisse müssen sinnvoll linear angeordnet werden
• Informationen sollen nach Möglichkeit nicht redundant aufgenommen werden, das Dokument aber gleichzeitig leicht lesbar sein.

Und Sie sehen: Der erste Punkt macht die Anwendung von Regel 1 „Schreibe Dokumentation aus Sicht des Lesers“ recht schwierig. Den Leser gibt es gar nicht.

Wirkungsvolle Architekturdokumentation

Dass die Regeln zwar sinnvoll klingen, ihre Anwendung in der Praxis aber ihre Tücken hat, habe ich in vielen Vorhaben erlebt. Denn ich beschäftige mich nun schon länger mit dem Thema Architekturdokumentation (zum Beispiel in meiner Kolumne im Java Magazin). Mit verschiedenen Projekten durfte ich gemeinsam Lösungen zu dem Thema erarbeiten.

Mittlerweile habe ich angefangen, meine Erfahrungen in einem Buch zusammenzuschreiben. Es soll den Lesern konkret anwendbare Hilfestellung bei ihrer Architekturdokumentation geben. Einfache Universalantworten habe ich aber nicht parat. Aber das Buch macht die sieben Regeln für gute Dokumentation durch praxiserprobte Werkzeuge und durchgängige, konkrete Beispiele erlebbar.

In diesem Blog möchte ich ab und über meine Fortschritte berichten. Bleiben Sie dran, über Feedback freue ich mich.