Die Kommunikatorin

Arten von Dokumenten

Als Kommunikatorin sollten Sie sich überlegen, welche Art von Dokumentation Sie gemäß den obigen Stilregeln schaffen können.

  • Ein Referenzdokument, z. B. nach der Kapitelgliederung von ARC42. Das ist Ihr Repository zum Festhalten aller architekturrelevanten Entscheidungen.
  • Falls Sie das Referenzdokument nicht schaffen, dann wenigstens einen 40 bis 50-seitigen „Architecture Guide“. Das ist eine Kurzfassung mit den wesentlichen Kapiteln des Referenzdokuments und meist noch weniger Tiefgang. Wohl aber den wichtigen Überblicksdiagrammen über Bausteinsicht, Verteilungssicht und Laufzeitsicht und kurzen Erläuterungen.
  • Eine Architekturpräsentation. Dafür reichen normalerweise 10 bis 20 Folien. Mit diesen sollten Sie jederzeit 30 bis 60 Minuten Ihre Architektur vorstellen, erläutern und verteidigen können. Im Wesentlichen sind das die Kernbilder aus der Architekturdokumentation (hoffentlich kopiert und nicht neu abgezeichnet) mit den Erläuterungen auf der Tonspur. Gute Tipps für die inhaltliche Gestaltung und den dramaturgischen Aufbau finden Sie in [4] bis [7]. Schmökern Sie in diesen Quellen in Ihrer Freizeit, denn Ihr Job als Kommunikatorin ist mindestens so wichtig wie als technische Entscheiderin.
  • Falls Sie doch – wie viele – die Dokumentation mit Word und Visio in Form von vielen Dateien erstellen, dann hilft ein „read-me“-Dokument, dass erläutert, welches Dokument welchen Inhalt hat und wie diese zusammenhängen.
Feste Gliederungen

Feste Gliederungen erleichtern Ihnen als Architekt das Erstellen von Dokumentation – und Ihren LeserInnen das Verständnis. Betrachten Sie als Beispiel ein typisches Fachbuch einer beliebigen Disziplin: Wir erwarten ein Inhaltsverzeichnis zu Beginn und ein Stichwortverzeichnis am Ende. Beides sind feste Struktur(vereinbarungen) – die uns als Leser dieses Fachbuchs das Leben etwas erleichtern. Wir schlagen (mal wieder) arc42 vor.

Stakeholder-gerecht kommunizieren

Nicht jeder im Projekt muss alles wissen und hören. Als geschickte Kommunikatorin versorgen Sie jeden mit der notwendigen Information. Dabei hilft es, wenn Ihre Dokumentation möglichst automatisch für unterschiedliche Personen in geeigneter Form aufbereitet werden kann. Sie wollen ja manuell möglichst keine Redundanz pflegen. Mit Word und Co. ist das recht schwierig. Leichter schon mit Repository-basierten Modellierungstools, aus denen Sie maßgeschneiderte Dokumente erzeugen können – allerdings um den Preis komplexer Bedienung und UML-Lastigkeit. Wikis bieten einen prima Kompromiss – sie bekommen damit Versionierung und Mehrbenutzerfähigkeit geschenkt und können benötigte Diagramme relativ leicht integrieren. Wählen Sie für die Dokumentation ein Medium, dass Ihnen möglichst große Flexibilität in der Gestaltung des Outputs bei möglichst geringem manuellen Aufwand gibt. Alles was Sie redundant erstellen müssen, wird zwangsläufig veralten und an Wert verlieren.

Fazit

Nichts zu dokumentieren halten wir für fahrlässig. Kommunizieren und Dokumentieren gehören zu den wesentlichen Tätigkeiten (und Verantwortungen!) von Softwarearchitekten. Für die Langlebigkeit, Änderbarkeit und Verständlichkeit von Software müssen Sie eine angemessene Menge an Dokumentation erstellen – deren Wert möglicherweise erst in der Zukunft sichtbar wird. Bleiben Sie pragmatisch und sparsam und betrachten Dokumentation als eine Versicherung gegen zukünftige Probleme.

Der iSAQB-Lehrplan

Das Kapitel 2 des iSAQB Lehrplans handelt von Beschreibung und Kommunikation von Softwarearchitekturen. Es gibt folgende Lernziele vor:

Können
  • Softwarearchitekturen adäquat für verschiedene Stakeholder beschreiben und kommunizieren
  • Qualitätsmerkmale technischer Dokumentation beachten (Verständlichkeit, Korrektheit, Effizienz)
  • verschiedene Architektursichten geeignet dokumentieren
  • Schnittstellen verständlich beschreiben und kommunizieren
  • Technische Konzepte (Persistenz, Verteilung, Kommunikation, …) dokumentieren und vermitteln
Verstehen
  • Templates für standardisierten Aufbau von Architekturdokumenten (z. B. arc42)
  • Template-Vorgaben für Black-Boxen, White-Boxen, Knoten, Schnittstellen
  • Geeignete UML-Diagramme für die unterschiedlichen Sichten
  • Dokumentation von unterschiedlichen Autoren (Architekt, Entwickler, Handbuchautoren) für unterschiedliche Stakeholder (Management, Entwickler, Qualitätssicherer, andere Softwarearchitekten)
Verstehen
  • Grundlagen einiger publizierter Frameworks, wie arc42, TOGAF, IEEE-1471
  • Mögliche Werkzeuge zur Erstellung und Pflege der Dokumentation
Peter Hruschka (www.systemsguild.com) und Gernot Starke (innoQ-Fellow, www.gernotstarke.de) haben vor einigen Jahren www.arc42.de ins Leben gerufen, das freie Portal für Softwarearchitekten. Sie sind Gründungsmitglieder des International Software Architecture Qualification Board (www.iSAQB.org) sowie Autoren mehrerer Bücher rund um Softwarearchitektur, Softwareentwurf und Entwicklungsprozesse.
Kommentare

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht.