Modellbasierte und textuelle Systemdokumentation UML - mehr als nur Bilder

Die Verbreitung der modellbasierten Dokumentation auf Basis der UML nimmt stetig zu, trifft jedoch auch oft auf Ablehnung: Durch vorgeschriebene textuelle Dokumentation entsteht Informationsredundanz, die den Wartungsaufwand erhöht. Tatsächlich ist es jedoch möglich, modell- und textbasierte Dokumentation zusammen ohne unnötigen Arbeitsaufwand zu verwenden.

Die Unified Modeling Language (UML) ist seit vielen Jahren ein Standard zur Analyse und zum Entwurf von Systemen. Insbesondere die grafische Notation und die definierte Semantik der Elemente verhilft ihr zur Akzeptanz. Immer mehr Unternehmen setzen in der Systementwicklung auf UML als Quasi-Standard zur modellbasierten Dokumentation. Dies trifft bei Entwicklern allerdings auf gemischte Gefühle.

Zwar erkennen viele von ihnen die theoretischen Vorteile, jedoch steigt auch die Skepsis. Im praktischen Einsatz sehen viele Entwickler einen Mehraufwand: Der Entwicklungsprozess schreibt bestimmte textuelle Entwicklungsdokumente vor - eine modellbasierte Dokumentation mit dieser Sprache bedeutet zusätzlichen Aufwand zur Erstellung, Pflege und Synchronisation der Inhalte.

Dieser Umstand führte bereits oft zur Ablehnung der UML mit der Begründung sie passe zeitlich nicht in den Entwicklungsprozess. Zwei Beispiele sollen im Folgenden jedoch deutlich machen, dass eine modell-basierte Dokumentation mit UML keinen Mehraufwand darstellen muss und wie modell- und textbasierte Dokumentation sich gegenseitig ergänzen.

Der prinzipielle Ablauf ist in Bild 1 kurz dargestellt.

Modellierung mit UML

Zur Erstellung von UML-Modellen stellt die Spezifikation eine umfangreiche Sammlung von Diagrammarten und Modellelementen zur Verfügung. Um dem Ziel eines konsistenten und einheitlich verständlichen UML-Modells möglichst nahe zu kommen, empfiehlt es sich, Modellierungsrichtlinien zu definieren. Diese enthalten:

  • Beschränkung auf eine Auswahl an Diagrammen und sinnvollen Modellelementen,
  • Richtlinien, wie mit Lücken und mehrdeutigen Angaben in der UML-Spezifikation umzugehen ist (Semantic Variation Points), sowie
  • Vorgabe von Modellstrukturen zur Ablage der Informationen.

UML-Werkzeuge können häufig die Einhaltung der Spezifikation automatisch überprüfen, genauso wie das Einhalten von Modellierungsrichtlinien. Dazu bedarf es eines Werkzeugs, das Modellierungsrichtlinien in der OCL (Object Constraint Language) oder einer ähnlichen Sprache auswerten kann. Hierzu sind oft neben UML-Werkzeugen externe Tools wie beispielsweise »GeneSEZ« notwendig.

»GeneSEZ«-Framework
Das Framework »Generative Software Entwicklung Zwickau« (GeneSEZ, gesprochen: Genesis) ist ein Forschungsprojekt der westsächsischen Hochschule Zwickau (WHZ). Es ist als Open-Source verfügbar und basiert technologisch auf dem Eclipse Modeling Projekt. Durch Adapter können unterschiedliche Modellierungswerkzeuge angebunden und in verschiedene Ausgabeformate (etwa Dokumentation oder Quellcode) transformiert werden.

Einige UML-Werkzeuge bieten Reporting-Funktionen, um Modellinformationen auszuwerten und Dokumente zu erstellen. Häufig erscheinen diese Erstellungsprozesse etwas schwerfällig, da sie sich in Bezug auf Aufbereitung der Modellinformationen und Dokumentenstrukturen nur sehr eingeschränkt anpassen und erweitern lassen. Dies gilt allerdings meist nicht für Werkzeuge auf Open-Source-Basis.

Häufig sind die zu erstellenden Dokumente, beispielsweise ein Glossar oder eine Schnittstellenbeschreibung, durch den Entwicklungsprozess vorgegeben. Der Aufbau und die Inhalte der Dokumente unterliegen projekt- und/oder unternehmensspezifischen Richtlinien. In den seltensten Fällen besteht eine vollständige Übereinstimmung der in Dokumenten und UML-Modellen enthaltenen Informationen.

Die inhaltliche Überschneidung ist vom Detaillierungsgrad der Modelle abhängig. Im Falle von Schnittstellenbeschreibungen und Glossaren ist dieser sehr hoch, jedoch gibt es immer wieder Informationen, die sich nicht sinnvoll in UML-Modellen hinterlegen lassen und manuell gepflegt werden sollten, etwa Kopf- und Fußzeilen oder zusätzliche Beschreibungen. Je nach Dokumentenformat gibt es unterschiedliche Möglichkeiten, generierte und manuell zu pflegende Inhalte zu integrieren.

Bürosoftware wie Microsofts »Word«, »Open Office« oder »LibreOffice« stellen nur sehr eingeschränkte Möglichkeiten zur Inhalte-Referenzierung bereit, wobei generierte und manuell gepflegte Inhalte in einem Dokument verwaltet werden müssen. Hierzu gibt es grundsätzlich zwei unterschiedliche Herangehensweisen:

  • Definition von Bereichen im Dokument, an denen generierte Inhalte eingefügt werden, und
  • Definition von Bereichen im Dokument, an denen manuell gepflegte Inhalte eingefügt werden.

Lassen Aufbau und Struktur von Dokumenten größeren Spielraum oder kann der Großteil an Inhalten nicht sinnvoll aus UML-Modellen übernommen werden, so ist meist die erste Herangehensweise sinnvoll. Sind Aufbau und Struktur der Dokumente festgelegt und sind nur an einigen Stellen manuelle gepflegte Inhalte notwendig, so bietet sich die zweite Herangehensweise an, da hier zusätzlich zu den Informationen die Dokumentenstruktur automatisiert entsteht.

Bürosoftware stellt die Funktion »versteckter Text« zur Verfügung, die zur Kennzeichnung des Beginns und des Endes definierter Bereiche dienen kann. Bei alternativen Dokumentenformaten (siehe Kasten »Alternative Dokumentenformate«) können etwa Kommentare für definierte Bereiche zum Einsatz kommen oder es besteht die Möglichkeit zur Inhalte-Referenzierung und somit zur Trennung generierter und manuell zu pflegender Inhalte in verschiedene Dateien.

Alternative Dokumentenformate
Neben Office-Dokumenten gibt es mit Latex, DocBook und DITA (Darwin Information Typing Architecture) drei alternative und verbreitete Dokumentenformate. Typisch sind die logische Auszeichnung der Inhalte und die anschließende Transformation in Ausgabeformate (HTML, PDF, etc.). DocBook und DITA sind XML-basiert und standardisiert. Alle drei bieten Techniken zur Inhalte-Referenzierung und -Einbettung, um Dokumentenstrukturen flexibel zu gestalten. Mit Latex lassen sich Inhalte auf mehrere Dateien verteilen, die anschließend zu einem Dokument zusammengefügt werden. Bei den beiden XML-basierten Formaten bietet sich der XInclude-Mechanismus an. Damit lassen sich Inhalte anderer XML- oder auch Textdateien einbetten. Bei XML-Dateien lassen sich per XPath-Ausdruck Inhaltsteile auswählen und einbetten, wodurch sich eine höhere Flexibilität als bei Latex ergibt. Das Referenzieren und Einbetten von Inhalten kann genutzt werden, um generierten und manuell zu pflegenden Inhalt in verschiedenen Dateien zu verwalten. Dadurch können passive Generatoren zum Einsatz kommen, und man kann auf definierte Bereiche für generierten bzw. manuell zu pflegenden Inhalt verzichten.

Beispiel: Glossar

Im Sinne eines einheitlichen Verständnisses innerhalb eines Projekts ist es sinnvoll, ein Glossar zu führen, das domänenspezifische Begriffe definiert. Missverständnisse unter den Projektbeteiligten lassen sich dadurch vermeiden.

Auf Modellebene können Begriffe in Form von UML-Klassendiagrammen definiert werden. Das so genannte Begriffsmodell stellt eine erweiterte Form eines Glossars dar. Um ein Begriffsmodell zu erstellen, verwenden wir die folgenden Modellierungsrichtlinien:

  • Begriffe werden als Klasse modelliert.
  • Beziehungen zwischen Begriffen werden durch Assoziationen, Aggregationen oder Vererbung festgehalten.
  • Die Begriffsdefinition wird als Kommentar zur Klasse hinzugefügt, die optional auch grafisch im Diagramm angezeigt werden kann (abhängig vom UML-Werkzeug).
  • Eventuell weiterführende Begriffsdetails werden als Eigenschaften (engl. Properties) der Klasse hinzugefügt; wenn notwendig oder sinnvoll, lässt sich diesen Eigenschaften ebenfalls eine weitere Erklärung mit Kommentaren hinterlegen.

Bild 2 zeigt im linken Teil einen Ausschnitt eines Begriffsmodells für die Domäne Pkw.

Darin ist ein Auto mit seinen vier Eigenschaften Länge, Breite, Farbe und Typ dargestellt. Es kann vier oder fünf Sitze haben, wobei jeder Sitz zu genau einem Auto gehört.

Sitze haben die zwei Eigenschaften Farbe und Muster. Ein Auto hat genau ein Radio, und ein Radio ist in genau einem Auto verbaut.

Es gibt verschiedene Autos, in unserem Beispiel sind Trabant und Wartburg zu sehen.

Unser Glossar soll im Wesentlichen die Begriffe definieren und uns die Zusammenhänge zwischen den Begriffen aufzeigen. Wir wollen das Glossar nach den folgenden Gliederungsebenen erstellen:

  • Überschrift beziehungsweise Bezeichnung des Begriffs-modellausschnitts mit UML-Diagramm,
  • Begriffe mit ihrer Definition und Beziehungen als Glossareintrag und
  • eventuell weitere Details der Begriffe mit ihrer Erklärung.

Begriffe, ihre Definition sowie die Begriffsdetails können direkt aus dem UML-Modell kommen. Um die Beziehungen zwischen den Begriffen in eine textuelle Beschreibung abzubilden, kann der Diagramm-Sprache-Diagramm-Ansatz dienen. Die Nummern in Bild 2 verdeutlichen den Zusammenhang zwischen Informationen im UML-Modell und dem Glossarinhalt.

Der rechte Teil in Bild 2 zeigt einen Ausschnitt eines möglichen automatisch erzeugten Glossars. Der Inhalt eines solchen Glossars lassen sich vollständig aus dem Begriffsmodell übernehmen. Glossare werden häufig nicht als eigenständige Dokumente geführt, sondern meist als Bestandteil einer Entwicklungsdokumentation. Unterstützt das Dokumentenformat Referenzen auf Inhalte, genügt ein passiver Generator, um ein Glossar zu erzeigen.

Unterstützt das Werkzeug keine Inhaltsreferenzen oder werden beispielsweise die Begriffsdefinitionen im UML-Modell nicht gepflegt, so können aktive Generatoren mit definierten Bereichen für manuell zu pflegende Inhalte nützlich sein.

Aktive und Passive (Dokument-)Generatoren
Bei der automatisierten Erstellung von Artefakten aus Modellen lassen sich zwei Arten von Generatoren unterschieden. Passive Generatoren erstellen automatisierte Artefakte. Wird an den Artefakten etwas manuell verändert und der Generator erneut gestartet, um Änderungen am Modell zu übernehmen, so gehen manuelle Änderungen verloren. Bei aktiven Generatoren bleiben manuell erstellte Inhalte in speziellen Bereichen bei erneuter Ausführung des Generators erhalten. Passive Generatoren sind meist einfacher zu realisieren als aktive. Die Funktionsweise eines passiven Generators ist beispielsweise ähnlich der Serienbrief-Funktion in Bürosoftware: bestimmte Stellen im Dokumant werden durch Modellinformationen ersetzt.