menu Navigation
„Frag das Team!“ für Architekturdokumentation?

„Frag das Team!“ für Architekturdokumentation?

20. Juli 2011

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.

EntwicklerEntscheiderArchitekt

Das agile Team (v.l.n.r. Entwickler, Entscheider, Architekt) hat bestimmt eine Antwort ... Einfach fragen.

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.

2 Antworten zu “„Frag das Team!“ für Architekturdokumentation?”

  1. Malecki sagt:

    Hallo Herr Zörner,

    mir fallen einige Kommentare / Verbesserungsmöglichkeiten der Regeln für eine gute Dokumentation (u.A. auch Systemarchitektur) ein:

    1. Schreibe Dokumentation aus Sicht des Lesers

    -> schreibe, was der Leser verstehen kann

    2. Vermeide unnötige Wiederholungen

    -> treffe die Aussagen nur einmal im Dokument; wenn notwendig, verweise darauf

    3. Vermeide Mehrdeutigkeit

    -> sei eindeutig

    4. Verwende eine Standardstrukturierung

    -> mit den Standards für die Dokumentstrukturen ist es manchmal schwierig: entscheidend ist die Anpassug an die Zielgruppe und den Inhalt

    5. Halte Begründungen fest

    -> für Architekturentscheidungen, wo Alternativen möglich sind

    6. Halte Dokumentation aktuell, aber nicht zu aktuell

    -> warum diese Zurückhaltung? (Vermeiden von „Schnellschüssen“?). Entweder ist etwas eine Architektur oder eine Idee (hier geht es um einen geordneten Prozess der Entwicklung…)

    7. Überprüfe Dokumentation auf Gebrauchstauglichkeit

    -> das kling komplementär zu 1)

    Zusatzregel zu 3 (praktische, erste Umsetzungsregel) könnte sein: verwende immer einen Begriff für einen Sachverhalt (keine Synonyme), da ein z.B: eine Architekturdokumentation keine Belletristik ist (auch wenn wohl häufig als Bettlektüre eingesetzt wird…).

    Gruß

    Piotr Malecki

    • Hallo Hr. Malecki,

      Vielen Dank für Ihre Anregungen! Kurz zu zwei Ihrer Punkte. Der Unterschied der Regeln 1 und 7 ist aus meiner Sicht, dass ich mir im Vorfeld Gedanken über meine Zielgruppe machen muss (Regel 1), weshalb mir Ihr Hinweis zu 4 auch gut gefällt. Regel 7 („Überprüfe Dokumentation auf Gebrauchstauglichkeit“) lebe ich bezüglich Architekturdokumentation so, dass ich mir die Zeit nehme, aktiv Feedback von Lesern (z.B. neuen Mitarbeitern) einzuholen, und in die Dokumentation einfließen zu lassen.

      Die Regeln sind ja nicht von mir, ich „deute“ die Aussage „6. Halte Dokumentation aktuell, aber nicht zu aktuell“ in Bezug auf Architekturdokumentation vor allem als Aufforderung, die Inhalte von vornherein so zu erstellen, dass ich sie nicht alle Nase aktualisieren muss. In einen Architekturüberblick beispielsweise als Laufzeitumgebung Java SE 1.6.0_24-b07 und Tomcat 7.0.21 anzugeben, ist kein guter Plan. Java SE 6 und Tomcat 7 tut es auch ;-)

      Herzliche Grüße,
      StefanZ

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.