transentis consulting

Einführung in die Modellgetriebene Dokumentation

Automatisch Dokumente und Websites aus Enterprise Architect Model generieren
  • Robert Pagel
    Robert Pagel
    Monday, December 3, 2012
Ein Überblick darüber, wie man Enterprise Architect Modelle einem breiten Publikum zur Verfügung stellt, indem man sie automatisch in Dokumente, Poster oder Webseiten konvertiert
Um die Komplexität ihres Geschäfts beherrschen zu können, nehmen viele unserer Kunden Modelle zu Hilfe. Oft investieren sie tausende Stunden und ein erhebliches Budget, um Geschäftsmodelle, Geschäftsprozesse, Organisationsstrukturen oder IT-Systeme zu visualisieren.
Nach unserer Erfahrung werden diese Modelle leider oft nur von denjenigen genutzt, die sie ursprünglich erstellt und bearbeitet hatten. Die darin enthaltenen Informationen könnten aber viel mehr Kollegen von Nutzen sein, wären sie leichter zugänglich.
Einige Firmen versuchen deshalb, ihre Mitarbeitern in Modellierungssprachen und -werkzeugen zu schulen. Dieser Ansatz bindet die Mitarbeiter über längere Zeit, die zumeist nicht besonders daran interessiert sind, diese Themen zu verinnerlichen. Es ist für sie, als müssten sie eine neue Sprache lernen, um ein Dokument lesen zu können, das leider nicht in ihrer Sprache vorliegt.
Unser Ansatz ist es, stattdessen das Dokument zu übersetzen. Wir konvertieren Modelle in leicht verständliche Dokumente, Poster oder Websites und machen sie so einer breiten Zielgruppe zugänglich.
Das Generieren von Dokumenten aus Modellen bieten wir seit vielen Jahren als Dienstleistung für Unternehmen an. Unser erstes modellgetriebenes Dokument entstand vor über zehn Jahren als ein web-basiertes und prozess-orientiertes Qualitätshandbuch. Es wurde aus einem UML-Modell generiert, das Geschäftsprozesse beschrieb. Seitdem wurden wir mit der Erstellung von einer Vielzahl von Dokumenten beauftragt, von simplen Tabellen zur Unterstützung von Projektmanagern über Prozesshandbücher bis hin zu großen web-basierten Architekturportalen.
In diesem Artikel möchte ich drei grundsätzliche Punkte behandeln:
  • Eine Einführung in die Idee der modellgetriebenen Dokumentation
  • Ansätze für die Erstellung eines Frameworks für modellgetriebene Dokumentation
  • Die Bausteine eines Prozesses für modellgetriebene Dokumentation

Das Konzept der modellgetriebenen Dokumentation

Wie oben beschrieben ist die Idee hinter model-driven documentation recht simpel, ihre Umsetzung in die Praxis erfordert jedoch Disziplin. Statt ein Modell zu erstellen und zu hoffen, dass die Leser es verstehen, sollte man besser:
  • Das Modell in einem graphischen Modellierungswerkzeug erstellen
  • Dokumentationstexte im gesamten Modell einfügen
  • Aus dem Modell Dokumente generieren
Diese simple Zusammenfassung muss für größere Projekte verfeinert und konkretisiert werden. Wie dies aussehen kann, werde ich in “Die Bausteine eines Prozesses für modellgetriebene Dokumentation” erläutern.
Um Ihnen ein konkretes Beispiel für diesen Artikel zu liefern, werde ich ein kleines Modell eines Internet-Archivs verwenden, das einige domänenspezifische Eigenheiten in der Modellierung besitzt.
Beispielmodell
Modellgetriebene Dokumentation ist nicht an ein bestimmtes Modellierungswerkzeug gebunden. Für dieses Beispiel haben wir die Software ®Enterprise Architect (EA) von unserem Partner Sparx Systems gewählt. Unser Beispielmodell beschreibt ein System aus verschiedenen Komponenten und wie sie miteinander interagieren. Es nutzt durchweg die klassische UML-Modellierung, aber für die Abbildung der Interaktion zwischen Komponenten gibt es eine domänenspezifische Konvention:
  • Für eine Übersicht, welche Komponenten überhaupt miteinander kommunizieren, werden sog. “Korridore” abgebildet. In das Modell werden sie als Assoziationen eingefügt. Der Name jedes Korridors ist eine eindeutige Nummer.
  • In der Detailsicht wird für jeden Korridor ein Bündel “Kanäle” angezeigt. Die Komponenten besitzen für jeden Kanal ein ExposedInterface und jeweils zwei ExposedInterfaces sind per Information Flow verbunden. Jeder Kanal steht für die Übertragung mindestens einer Nachricht. Diese Art der Modellierung versteckt Details, wenn die Übersicht betrachtet wird, kann sie aber bei Bedarf anzeigen.
Unser Beispiel beschreibt vier Komponenten eines Internet-Archivs. Kontinuierlich lädt es Websites mit einem Crawler aus dem Netz herunter, speichert diese in ein Archiv und erstellt einen Index, um das Archiv später durchsuchen zu können. Es stellt außerdem ein web-basiertes Frontend bereit, mit dem Websites betrachtet werden können, als wären sie immernoch online. Als Übersicht sieht dies folgendermaßen aus:
Zusätzlich zu den Komponenten beinhaltet das Modell Prozesse, die die Abläufe des Systems beschreiben. Jede involvierte Komponente wird repräsentiert durch eine Partition. Partitionen enthalten Aktionen und Aktionen sind wiederum mit ControlFlows oder ObjectFlows verbunden. ControlFlows werden im Gegensatz zu ObjectFlows benutzt, wenn sich beide Aktionen in der gleichen Partition befinden.
Ihr Modell ist wahrscheinlich deutlich größer, enthält eine Vielzahl von Diagrammen und besitzt andere domänenspezifische Eigenheiten. Der in diesem Artikel vorgestellte Ansatz ist aber allgemein genug, um ihn auf jede Art von Modell anzuwenden.
Nehmen Sie einmal an, Sie würden gerne aus diesem Modell ein Dokument generieren, das sie ausdrucken und jemandem in die Hand geben können, damit sie oder er das vom Modell beschriebene System versteht. Dieses Dokument sollte wahrscheinlich mit einer Einleitung beginnen, die den Zweck und die Abgrenzung des Modell erklärt. Darauf könnte dann ein Kapitel folgen, das jede Komponente und jede Schnittstelle im Detail beschreibt und am Ende des Dokuments könnte ein Kapitel über die Prozesse stehen.
EA enthält bereits eine integrierte Reporting-Funktion. Damit lassen sich RTF-Dokumente erstellen, die Sie mit Textverarbeitungesprogrammen editieren können. Sie können auch Templates erstellen für Pakete und Elemente, können Elemente aus dem Ergebnis herausfiltern und es gibt eine Fülle an Einstellungsmöglichkeiten.
Sobald Sie die Reporting-Funktion wie gewünscht konfiguriert haben, können Sie ihr RTF-Dokument erstellen. Danach fügen Sie am Beginn des Dokuments die Einleitung ein und ändern schließlich das Styling des Dokuments, um dem Ihrer Firma zu entsprechen. Falls die Reihenfolge der Elemente, die von EA ausgegeben werden, noch nicht Ihren Vorstellungen entspricht, müssen Sie diese noch ändern.
Falls Sie sich noch ein Kapitel wünschen, das alle Nachrichten auflistet und für jede zeigt, zwischen welchen Komponenten sie verschickt wird, müssen Sie dieses Kapitel per Hand erstellen. Mit der EA-internen Reporting-Funktion ist dies nur schwer oder gar unmöglich zu schaffen. Sie müssten für jede Nachricht jeden Kanal finden, über den sie transportiert wird und dann jeweils die beiden Komponenten auflisten, die zu den ExposedInterfaces gehören, die der Kanal verbindet und dabei doppelte Nennungen herausfiltern.
Die größte Schwierigkeit dieses Ansatzes ist allerdings, dass Sie die meisten der oben genannten Vorgänge per Hand erledigen müssen. Dies macht die Erstellung der Dokumente unnötig langsam und fehleranfällig. Kleine Änderungen im Modell könnten Sie noch per Hand im Dokument nachziehen, aber bei größeren Änderungen des Modells wird es schnell unübersichtlich.
Im nächsten Abschnitt schauen wir uns an, wie Sie diese Situation lösen können.

Ansätze für die Erstellung eines Frameworks für modellgetriebene Dokumentation

Für das Generieren komplexer Dokumente verlassen wir uns selten auf die vom Modellierungswerkzeug bereitgestellten Werkzeuge. Stattdessen nutzen wir ein eigenes Programm, den “ModelExporter”, das ein Modell komplett in ein spezielles XML-Format exportiert.
Für jedes Dokument, das wir aus dem Modell generieren, definieren wir eine oder eine Kette mehrerer XSL-Transformationen, die auf dem exportierten XML arbeiten und daraus Dokumente im gewünschten Format erstellen:
  • Für die Erstellung von Text-Dokumenten im PDF-Format nutzen wir nutzen wir das LaTeX-ähnliche Docbook Framework.
  • Um Websites aus Modellen zu erstellen, nutzen wir HTML5 and CSS3 als Grundgerüst, Javascript für Interaktionen und kodieren das Modell im JSON-Format.
  • Für die Erstellung von Tabellen nutzen wir das CSV-Format.
Dieser modulare Aufbau der Dokumentgenerierung aus Exporter und XSL-Transformationen verbessert die Generierung auf mehreren Wegen:
  • Ein mit dem ModelExporter erstelltes XML lässt sich leicht mit anderen XML-Dokumenten kombinieren, um z.B. Anforderungen aus einem separaten Repository oder statischen Text wie eine Einleitung einzufügen.
  • XSL ist eine mächtige Transformationssprache für XML, mit der Dokumente beliebig strukturiert werden können. Docbook ist ebenfalls als XSL-Transformation implementiert.
  • Diagramme werden als Vektorgrafiken übernommen, was beliebiges Zoomen ohne Artefaktbildung erlaubt.
  • Der gesamte Prozess ist über Skripte automatisierbar. Sobald Sie aus Ihrem Modell Dokumente generieren möchten, können Sie diese aus dem “Tools” Menü von EA bequem aufrufen.
Wie dieser Prozess für die Erstellung von PDF-Dokumenten mit Docbook abläuft, illustriert das nächste Schaubild. Die Komponente “Crawler” im Modell wird zunächst mit dem ModelExporter in XML umgewandelt. Eine XSL-Transformation erstellt daraus XML im Docbook-Format, wobei die Struktur des Dokuments festgelegt wird. Daraus wird wiederum XML im FO-Format erzeugt, hier fließen Styling-Informationen aus dem anpassbaren “Customization Layer” von Docbook mit ein. Aus dem FO-XML können dann FO-Prozessoren wie Apache FOP oder Antenna House ein PDF-Dokument erstellen.

Elemente eines modellgetriebenen Dokumentationsprozesses

Wenn Sie modellgetriebene Dokumentation in einem Projekt nutzen möchten, macht es Sinn, zunächst die verschiedenen Gruppen von Lesern zu identifizieren und in Erfahrung zu bringen, welche Informationen sie jeweils benötigen. Mit diesem Wissen können Sie Gliederungen für die benötigten Dokumente entwerfen und sich jeweils für ein oder mehrere Zielformate entscheiden. Gleichzeitig können Sie den Aufbau ihres Modells planen und mit welchen UML-Elementen sie ihr System modellieren. Je konsistenter Sie planen, desto einfacher wird später die Generierung von Dokumenten. Wir halten diese Entscheidungen gerne in Form eines Metamodells fest. Sobald sie wissen, wie ihr Modell aufgebaut sein wird und welche Dokumente sie generieren möchten, können Sie mit der Implementierung der XSL-Transformationen beginnen.
Das Docbook-Framework erlaubt die Erstellung sog. “Customization Layer”, welche die Formatierung der erstellten Dokumente festlegen. Wie ein CSS-Stylesheet für HTML ist es separat vom Inhalt des Dokuments anpassbar. Sollte sich also die Vorgabe für Ihr Firmenlayout ändern, müssen Sie nur den Customization Layer anpassen, egal wie viele Dokumente sie generieren.
Ist dieser Prozess einmal etabliert, ist er leicht erweiterbar. Sie können mehr und mehr Wissen in ihrem Modell unterbringen und es zu Ihrer zentralen Informationsquelle machen. Wenn das Modell zu groß wird, um durch eine Person gepflegt zu werden, werden Sie die Hilfe Ihrer Kollegen benötigen, um etwa große Datenimporte oder Anpassungen unter Zeitdruck durchzuführen. Ihren Kollegen müssen Sie dann erklären, wie das Modell aufgebaut ist und welche UML-Elemente wofür stehen. Es ist wichtig, dass jeder Mitarbeiter die Konventionen Ihrer Modellierung versteht und konsequent anwendet.
EA bietet von Haus aus die Anbindung an Versionskontrollsysteme an. Sie können einzelne Pakete als “unter Versionskontrolle” markieren, so dass Änderungen an ihnen verfolgt und notfalls rückgängig gemacht werden können. EA nutzt einen exklusiven Locking-Mechanismus, um sicherzustellen, dass niemals zwei Mitarbeiter an dem gleichen Paket arbeiten und voneinander abweichende Änderungen vornehmen. Paketübergreifende Referenzen zwischen Elementen sind dadurch aber nicht geschützt und Ihr Modell kann durch Missverständnisse trotzdem inkonsistent werden.
Unserer Erfahrung nach macht jedes Modellierungsteam Fehler. Diese in großen Modellen händisch zu finden und zu korrigieren ist eine ermüdende Aufgabe, die nach jeder Änderung des Modells nötig ist. Da Sie Ihr Modell zu Ihrer zentralen Informationsquelle gemacht haben, ist die Bewahrung seiner Konsistenz besonders wichtig.
Als wir damals anfingen, unsere Kunden in der Pflege großer Modelle zu unterstützen, befassten wir uns intensiv mit ihrer automatischen Konsistenzprüfung. Wir fingen an, die impliziten und expliziten Regeln in einem Tool umzusetzen, das ein Modell überprüft und eine Liste sämtlicher Fehler erstellt. Die aktuelle Version unseres “ModelCheckers” ist bei derzeit einem großen Kunden im Einsatz und prüft dort ein Modell von etwa 10.000 Elementen, 6000 Konnektoren und 400 Diagrammen auf die Einhaltung von 30 Regeln. Eine komplette Prüfung dauert nur etwa drei Sekunden und als wir sie zum ersten Mal ausführten, wurden hunderte Fehler gefunden. Der ModelChecker kann wie die Dokumentgenerierung in das “Tools” Menü von EA hinzugefügt werden, wo ihn jeder Modellierer starten kann. Wie bei Unit-Testing in der Softwareentwicklung gewinnt das Team damit Selbstvertrauen, auch große Änderungen am Modell durchzuführen, da es sicher sein kann, dass dadurch keine schwer zu findenden Fehler entstehen.
Ich hoffe, dass Sie in diesem Artikel Ansätze finden konnten, wie Sie modellgetriebene Dokumentation in Ihrer Firma umsetzen können. Wenn Sie Fragen oder Verbesserungsvorschläge haben, freue ich mich über einen Kommentar.
Upcoming Events

Training AI to Play The Beer Distribution Game

2 hours - 2021-10-27

Mastering The Complexity of Digital Transformation

2 hours - 2021-10-28

Modeling Growth Strategies For Professional Service Firms

2 hours - 2021-11-18

Go to event overview

Recent Blogposts

Meetup: Agile Transformation Tools

Olga Medvedeva - 2021-09-27

Meetup: Understanding The Beer Distribution Game

Olga Medvedeva - 2021-09-01

Introduction to The Business Prototyping Toolkit

Oliver Grasl - 2021-08-17

Go to blog overview

Email newsletter

Subscribe to our newsletter and stay up to date about the latest trends and news.

Name
Email
Subscribe to our newsletter and stay up to date about the latest trends and news.
  • transentis
Contact us

transentis consulting

Geisbergstraße 9

10777 Berlin


+49 30 9203833320

info@transentis.com