Die durch die zuvor vorgestellten Verfahren getroffene Entscheidungen müssen für eine spätere Nachverfolgbarkeit notiert werden. Dies muss auf eine einheitlich strukturierte Art und Weise geschehen. Die Informationen müssen bei Bedarf schnell gefunden und erfasst werden können.
Eine zusätzliche Dokumentation der Anwendung ist wichtig. Es ist unmöglich das erforderliche Wissen, um eine Anwendung langfristig warten zu können, alleine aus dem Quellcode zu erhalten [37]. Bei einer Dokumentation muss nach den Adressaten unterschieden werden. Eine Dokumentation zur Installation und Inbetriebnahme einer Anwendung ist für den Kunden interessant und häufig ein Teil des Vertrages. Eine Beschreibung der Architektur und wie sie sich diese entwickelt hat ist für den Endkunden in den meisten Fällen stattdessen uninteressant.
Häufig ist es wichtig zu wissen, warum die Architektur sich entsprechend entwickelt hat. Zu diesem Zweck können Begründungen für Entscheidungen notiert werden. Eine Begründung kann z.B. eine Anforderung des Kunden sein oder eine technische Gegebenheit. Wenn dies nicht geschieht ist es zu einem späteren Zeitpunkt schwer alle Entscheidungen nachvollziehen zu können. In einer strukturierten und übersichtlichen Dokumentation wird es möglich An-haltspunkte für Änderungen zu finden, weil z.B. einzelne Begründungen nicht mehr zutreffen.
Diese Art der Dokumentation dient in erster Linie den Entwicklern und weiteren Stakeholdern wie z.B. Personen die ein Review durchführen. Wenn die wesentlichen Informationen vorhan-den sind kann sie als zentraler Bestandteil zur Kommunikation dienen [37]. Bei einer solchen Dokumentation ist es sehr wichtig, dass Beweggründe für Entscheidungen notiert werden, um diese später nachvollziehen zu können. Wenn die Beweggründe nicht mehr mit dem Ziel der Anwendung übereinstimmen kann dies ein Anzeichen dafür sein, dass eine Änderung notwendig ist.
Das Problem bei einer Architekturdokumentation ist häufig, dass diese sehr mühselig zu pflegen ist. In vielen Fällen ist ebenfalls nicht klar, wie eine Dokumentation im Idealfall aussehen sollte.
In traditionellen Vorgehensmodellen ist eine solche Dokumentation meist mehrere hunderte Seiten lang [48]. Dadurch ist es besonders schwer diese zu überprüfen, dauerhaft aktuell zu halten und in kurzer Zeit die erforderlichen Informationen zu finden.
Aus diesem Grund muss eine Möglichkeit gefunden werden, um eine leichtgewichtige Doku-mentation zu erzeugen. Eine leichtgewichtige DokuDoku-mentation sollte die Anforderung erfüllen in ihrer vollständigen Länge übersichtlich zu sein. Dies soll es außerdem ermöglichen sie in einer akzeptablen Zeit zu aktualisieren. Die Erstellung soll keinen exorbitanten Mehraufwand bedeuten. Die Dokumentation soll sowohl zuvor nicht an dem Projekt beteiligten Personen, wie auch Personen die das Projekt bereits kennen ermöglichen einen Überblick über den aktuellen Stand zu erhalten. Gründe und mögliche Alternativen für getroffene Entscheidungen sollten ein fester Bestandteil sein. Um diese Anforderungen zu erfüllen muss eine Vorlage für die Dokumentation im Projekt gewählt werden. Dazu werden ins folgendem Abschnitt zwei Ansätze vorgestellt.
4.7.1 Dokumentations Frameworks
Um eine Architekturdokumentation übersichtlich zu halten sollten feste Strukturen in dieser vorhanden sein. Durch die Struktur werden die Inhalte vorgegeben. In diesem Abschnitt werden zwei Vorlagen für eine Dokumentation vorgestellt und bewertet.
Framework A Hadar u.a. haben in [48] eine Spezifikation für eine kurze Dokumentation entwickelt. Dieses Dokument soll von den Architekten pro Release gepflegt werden.
Für eine möglichst klare und einheitliche Struktur ist die Dokumentation in fünf Abschnitte unterteilt. Zu Anfang wird eine Übersicht über das Produkt gegeben. Dazu werden die Ziele, Businesswerte und potenzielle Kunden in 100 Wörtern beschrieben. Im zweiten Abschnitt wird das Produktziel für den kommenden Release beschrieben. Damit die Beschreibung nur die wesentlichen Informationen enthält ist die Länge auf maximal 100 Wörter begrenzt. Der dritte Abschnitt beinhaltet eine Architekturübersicht über das aktuelle System. Geplante Änderungen für den nächsten Release werden zusätzlich beschrieben. Dies bedeutet, dass die aktuellen und zukünftigen Hauptkomponenten mit den geplanten Änderungen beschrieben werden. Dazu zählen ebenfalls Komponenten die neu hinzukommen. Dieser Abschnitt ist der Hauptbestandteil des Dokuments und ist auf 1000 Wörter begrenzt. Der vierte Teil beschreibt die grundlegenden Anforderungen. Statt in Textform werden diese tabellarisch aufgezählt.
Zu jeder Anforderung wird notiert wie die nichtfunktionalen Anforderungen die Architektur beeinflussen. Der fünfte und letzte Abschnitt beinhaltet ein tabellarisches Acronym- und
Definitionsverzeichnis. Hier werden Abkürzungen erklärt. In jedem Abschnitt ist es erlaubt auf weitere relevante Dokumentation zu verweisen. Diese können sowohl von dem Produkt selber, wie auch von ähnlichen Produkten sein.
Um ihren Ansatz zu unterstützen haben Hadar u.a. ein Tool zur Erstellung der Dokumentation entwickelt. Dieses Tool beinhaltet ein Modellierungswerkzeug. Dadurch können alle relevanten Informationen entweder durch ein Formular oder direkt in dem Modell eingetragen werden.
Dieser Vorschlage bietet durch die klare Strukturierung eine Möglichkeit relevante Infor-mationen möglichst präzise aufzuschreiben. Die Begrenzung auf eine maximale Wortanzahl verpflichtet die Personen die schriftlichen Punkte übersichtlich und präzise zu halten. Durch die Möglichkeit auf weitere Dokumentation zu verweisen können Details zu speziellen Punkten ausgelagert werden. Das entstehende Dokument bietet dadurch einen Gesamtüberblick der Architektur und der Ziele für den nächsten Release. Bei Bedarf kann in zusätzliche, verlinkte Dokumente für weiterführende Informationen und Details gesehen werden.
Framework B Der zweite Ansatz, um eine Dokumentation durchzuführen, stammt von Van Heesch u.a [79]. Sie sagen, dass es unmöglich ist eine Architekturdokumentation zu erzeugen die für alle Stakeholder geeignet ist. Jede Gruppe von ihnen benötigt einen unterschiedlichen Viewpoint. Die Dokumentation einer Architkektur ist laut ihnen eine Sammlung der getroffenen Architektur-Entscheidungen. In ihrem Ansatz setzten sie vier unterschiedliche Viewpoints ein. Diese sollen einen Großteil der Stakeholder-Interessen befriedigen. Dieses Framework beinhaltet die folgende Viewpoints und deren beschriebenen Umsetzungen.
Entscheidungsdetails Um die Details einer Entscheidung zu beschreiben wurde ein Tem-plate mit fest definierten Punkten entwickelt. Folgende nur genannte Einträge sollen ausgefüllt werden: Namen, Status, Entscheidungsgruppe, Problem, Entscheidung/Lösung, Alternativen, verwandte Entscheidungen, Beziehungen zu Systemeigenschaften (z.B.
funktionale und nichtfunktionale Anforderungen) und Historie. Eine genaue Beschrei-bung der einzelnen Punkte ist aus der original Arbeit zu entnehmen.
Entscheidungs Beziehungen In diesem Viewpoint werden mithilfe eines grafischen Netz-werkes Beziehungen zu anderen Entscheidungen dargestellt. Dies können z.B. Auslöser, Abhängigkeiten oder auch Ersetzungen alter Entscheidungen sein. Ein Beispiel für solch einen Graphen ist in Abbildung4.2zu sehen.
Entscheidungs Chronologie Die Entwicklung der Entscheidung wird in diesem Punkt chro-nologisch beschrieben. Architektur Iterationen mit einem möglichem Datum sind
sicht-Abbildung 4.2: Entscheidungsbeziehungen als Graph [79]
bar. Dadurch kann nachvollzogen werden wann welche Entscheidungen verworfen und welche getroffen wurden.
Entscheidungs Stakeholder Beteiligung Dies beschreibt die Verantwortlichkeiten der ein-zelnen Stakeholder beim Entscheidungsprozess. Hier wird unter anderem beschrieben wer welche Informationen besitzt. Dies ist wichtig, da es nicht immer möglich ist alles vollständig und verständlich aufzuschreiben. Für die Darstellung kann z.B. eine ähn-liche Darstellung wie in einem Use-Case Diagramm gewählt werden. In diesem sind unterschiedliche Personen, inkl. deren Rolle, eingezeichnet. Die Personen können auf verschiedene Arten mit den Entscheidungsmöglichkeiten interagieren (z.B. Empfehlen, Zurückweisen, Validieren, Bestätigen).
Dieser Ansatz hat den Vorteile, dass der gesamte Entstehungsprozess notiert wird. Dadurch wird es möglich zu erkennen wann und wer zu dieser Entscheidung beigetragen hat. Außerdem ist erkennbar welche Alternativen in Betracht gezogen wurden und entweder aus bestimmten Gründen zurückgewiesen oder einfach nicht ausgewählt wurden. Dies kann vorkommen wenn eine ebenfalls akzeptable Lösung als besser empfunden wurde. Zu einem späteren Zeitpunkt kann so geprüft werden ob diese Entscheidung noch aktuell ist. Bei einer notwendigen Än-derung ist direkt ersichtlich welche weiteren Entscheidungen betroffen sind und eventuell ebenfalls angepasst werden müssen. Die Durchführung dieser Dokumentation kann durch die unterschiedlichen Grafiken schnell aufwendig werden. Es muss ein Prozess etabliert werden der annähernd zeitgleich beim Treffen der Entscheidungen die Informationen sammelt. Eine anschließende Dokumentation wird in der Regel zu ungenau.