Projektdokumentation per Knopfdruck

Wer den objectiF RM kennt, der weiß, dass Requirements Modelle nicht nur einfach als Bild in Word-Dokumenten abgebildet werden. Leicht können Sie Ihre Inhalte auch – individuell aufbereitet – in Dokumente übernehmen. Hinter dieser Tatsache steckt ein Generierungsmechanismus, der vielfältig konfigurierbar ist. Einmal damit vertraut, bietet dieser Mechanismus jedem Anwender eine Vielzahl an Möglichkeiten für zielgruppenorientierte Projektdokumentation – einfach per Knopfdruck.

Unser Standard-Template liefert bereits einige Dokumente und Dokumentvorlagen für Ihre Projektdokumentation mit. Aber wie das Leben nun einmal ist: Manchmal fehlt genau das, was man gerne hätte. So ging es auch einem unserer Kunden: Er benutzt Blockdiagramme der SysML, einer Erweiterung der UML, um Architekturaspekte zu spezifizieren. In Blockdiagrammen hatte er Schnittstellen modelliert, die jeweils über einen Standardport eine Use- bzw. Realize-Beziehung zu Blöcken seines Systems besaßen. Das sah etwa so aus:

Blockdiagramm der SysML in objectiF RM

Kundenwunsch: Projektdokumentation als Tabelle in MS Word umsetzen

In seiner Word-Dokumentation wünschte sich der Kunde nun eine Tabelle, die eine Schnittstelle mit ihren Beziehungen und den Blöcken als Einheit darstellte. Der Tabelleneintrag für eine Schnittstelle sollte aus dem Modell automatisch erzeugt werden und so aufgebaut sein:

Gewünschter Tabelleneintrag

Ein Blick in die vorhandenen Dokumente bzw. Dokumentvorlagen half ihm an dieser Stelle leider nicht weiter. Was jedoch half, war eine E-Mail an uns, an service@microtool.de :-)

Wir konnten ihm sagen: Diese Art von Projektdokumentation lässt sich mit objectiF RM erzeugen. Allerdings haben wir es hier mit einem speziellen Fall zu tun: Daten unterschiedlicher Modellelemente müssen ermittelt und in einer Tabelle zusammengeführt werden. Die Dokumentationstechnik des objectiF RM ist für eine solche Projektdokumentation auch gut geeignet, denn sie ist sehr universell und flexibel einsetzbar. Dokumentvorlagen lassen sich „bausteinartig“ miteinander verknüpfen und verschachteln – und nach Bedarf wiederverwenden.

Für das obige Beispiel beschreibe ich nun sehr detailliert, damit Sie es nachklicken können, was (einmal) getan werden muss, um (immer wieder) auf Knopfdruck das gewünschte Ergebnis zu erhalten. Wenn Sie Anwender des objectiF RM sind, können Sie so Ihre Projektdokumentation zukünftig einfach selbst gestalten.

Auf dem Weg zur eigenen Projektdokumentation

So geht’s: Sie benötigen mehrere Dokumentvorlagen, die Sie später zusammenbauen. Um sie zu erstellen, sind 5 Schritte notwendig (klingt komplizierter als es tatsächlich ist, da sich die Schritte zum Teil wiederholen):

1. Eine Dokumentvorlage, die den Namen des Blockes für einen Standardport ausgibt (wird benötigt, um in den unteren Zellen der gewünschten Tabelle (siehe oben) die Namen der Blöcke auszugeben)
2. Eine Dokumentvorlage für die Realize-Beziehungen (linke untere Zelle; diese benötigt Punkt 1)
3. Eine Dokumentvorlage für die Use-Beziehungen (rechte untere Zelle; diese benötigt Punkt 1)
4. Eine Dokumentvorlage für ein BlockInterface, welches die beiden oberen (2. und 3.) benutzt (gesamte obige Tabelle)
5. Eine Dokumentvorlage für ein Package, welches das Template aus Schritt 4 benutzt (Liste aller BlockInterfaces eines Package; d.h. Liste von Tabellen).

Schritt 1: Dokumentvorlage für den Standardport

Legen Sie bei den Dokumentvorlagen in Ihrem System eine neue Dokumentvorlage an. Wählen Sie einen passenden Namen. Als Stereotyp wählen Sie für dieses Beispiel «StandardPort» aus:

Auf dem Weg zur eigenen Projektdokumentation: Dokumentvorlage für Standardport anlegen

Bearbeiten Sie die Dokumentvorlage: Es soll nur der Blockname ausgegeben werden. Wählen Sie deshalb rechts in dem Textmarkenbereich bei Eigenschaft Block.Name aus. Klicken Sie anschließend auf den Button Einfügen. Das Dokument sollte dann so aussehen:

Bearbeiten der Dokumentvorlage für Standardport in MS Word

Speichern Sie das Dokument und schließen Sie Word.

Schritt 2: Dokumentvorlage für Realize-Beziehungen

Legen Sie bei den Dokumentvorlagen in Ihrem System eine neue Vorlage an. Wählen Sie einen passenden Namen. Als Stereotyp wählen Sie hier «StandardPortRealizesRelationship» aus.

Auf dem Weg zur eigenen Projektdokumentation: Dokumentvorlage für Realize-Beziehungen

Bearbeiten Sie die Dokumentvorlage: Fügen Sie zunächst den Text „über den Port“ ein. Klicken Sie dann vor diesen Text und wählen Sie rechts im Textmarkenbereich bei Eigenschaft ParentStandardPort und als Dokumentenvorlage Ihre in Schritt 1 definierte Vorlage. Klicken Sie dann auf den Button Einfügen. Jetzt klicken Sie unter den Text und wählen rechts im Textmarkenbereich bei Eigenschaft ParentStandardPort.Name aus. Klicken Sie anschließend wieder auf Einfügen. Das Dokument sollte jetzt so aussehen:

Bearbeiten der Dokumentvorlage für Realize-Beziehungen

Dieser Text wird später zum Text für die Realize-Beziehung in Ihrer Tabelle, dem generierten Bereich der linken unteren Zelle. Speichern Sie das Dokument und schließen Sie Word.

Schritt 3: Dokumentvorlage für die Uses-Beziehungen

Sie kennen das jetzt schon: Legen Sie bei den Dokumentvorlagen in Ihrem System eine neue Dokumentvorlage an. Wählen Sie einen passenden Namen. Als Stereotyp wählen Sie diesmal «StandardPortUsesRelationship» aus.

Auf dem Weg zur Projektdokumentation: Dokumentvorlage für Uses-Beziehungen anlegen

Bearbeiten Sie diese Dokumentvorlage: Fügen Sie zunächst den Text „über den Port“ ein. Klicken Sie dann vor diesen Text und wählen Sie rechts in dem Textmarkenbereich bei Eigenschaft ParentStandardPort und als Dokumentenvorlage Ihre unter Punkt 1 definierte Vorlage. Klicken Sie anschließend auf den Button Einfügen. Klicken Sie dann unter den Text und wählen Sie rechts im Textmarkenbereich bei Eigenschaft ParentStandardPort.Name aus. Klicken Sie wieder auf Einfügen. Das Dokument sollte jetzt so aussehen:

Bearbeiten der Dokumentvorlage für Uses-Beziehungen

Dieser Text wird später zu dem Text für die Uses-Beziehung in Ihrer Tabelle, dem automatisch generierten Bereich der rechten unteren Zelle. Speichern Sie das Dokument und schließen Sie Word.

Schritt 4: Eine Dokumentvorlage für ein BlockInterface

Nun wird die Tabelle zusammengebaut: Legen Sie bei den Dokumentvorlagen in Ihrem System eine neue Dokumentvorlage an. Wählen Sie einen passenden Namen. Als Stereotyp wählen Sie «BlockInterface» aus.

Projektdokumentation fast geschafft: Dokumentvorlage für Blockinterface anlegen

Bearbeiten Sie diese Dokumentvorlage: Fügen Sie die von Ihnen gewünschte Tabelle für ein Blockinterface ein (Eine Spalte, 3 Zeilen, letzte Zeile geteilt) in zwei Zellen. Klicken Sie in die Zelle der ersten Zeile und wählen Sie rechts im Textmarkenbereich bei Eigenschaft Name aus. Klicken Sie dann auf Einfügen. Danach klicken Sie in die Zelle der zweiten Zeile und geben „Beschreibung“ ein. In der nächsten Zeile der gleichen Zelle wählen Sie rechts im Textmarkenbereich bei Eigenschaft „Description“ aus. Klicken Sie anschließend auf Einfügen. In der linken Zelle der dritten Zeile der Tabelle geben Sie zunächst „Realisierendes Element“ ein. In der nächsten Zeile der gleichen Zelle wählen Sie rechts im Textmarkenbereich bei Auflistung „StandardPortRealizesRelationships“ und als Dokumentenvorlage die im Schritt 2 definierte Vorlage. Klicken Sie anschließend auf Einfügen. In der rechten Zelle der dritten Zeile der Tabelle geben Sie zunächst „Benutzendes Element“ ein. In der nächsten Zeile der gleichen Zelle wählen Sie rechts im Textmarkenbereich bei Auflistung „StandardPortUsesRelationships“ und als Dokumentenvorlage die unter Schritt 3 definierte Vorlage aus. Klicken Sie anschließend wieder auf Einfügen. Das Dokument sollte jetzt so aussehen:

Bearbeiten der Dokumentvorlage für Blockinterface

Weitere Formatierungen für die Farbgebung und Ränder der Zellen können Sie bei Bedarf natürlich zusätzlich festlegen. Wir wollen hier darauf verzichten. Speichern Sie das Dokument und schließen Sie Word.

Diese Dokumentvorlage kann nun benutzt werden, um alle BlockInterfaces eines Package in der Dokumentation in Tabellenform darzustellen:

Schritt 5: Eine Dokumentvorlage für ein Package

Legen Sie bei den Dokumentvorlagen in Ihrem System eine neue Dokumentvorlage an. Wählen Sie einen passenden Namen. Als Stereotyp wählen Sie «Package» aus.

Dokumentvorlage für ein Package anlegen

Bearbeiten Sie die Dokumentvorlage: Fügen Sie als Überschrift für ein Package einen von Ihnen gewünschten Text ein, der den Namen des Package mit enthält. Für den Namen wählen Sie rechts im Textmarkenbereich bei Eigenschaft „Name“ aus. Klicken Sie anschließend auf Einfügen. Nach einer Leerzeile wählen Sie dann in der nächsten Zeile rechts im Textmarkenbereich bei Auflistung „BlockInterfaces“ und als Dokumentenvorlage die in Schritt 4 definierte Vorlage aus. Klicken Sie wieder auf Einfügen. Das Dokument sollte jetzt so aussehen:

Bearbeiten der Dokumentvorlage für ein Package

Dokument speichern, Word schließen – nun haben Sie alle benötigten Vorlagen definiert.

Die Dokumentvorlagen für Ihre Produktdokumentation benutzen

Jetzt können Sie – wann immer Sie es benötigen – ein Word-Dokument anlegen, das die Vorlage aus Schritt 5 benutzt und Ihnen letztendlich alle gewünschten Informationen für Ihre Projektdokumentation gemeinsam liefert.

Dazu legen Sie bei den Dokumenten in Ihrem System ein neues Dokument an. Vergeben Sie einen Namen für das Dokument. Wählen Sie als Dokumentvorlage die unter Punkt 5 erstellte Vorlage. Als zu dokumentierendes Element wählen Sie bitte das Package, das Ihre zu dokumentierenden BlockInterfaces enthält.

Benutzen der Dokumentvorlage

Ist das neue Dokument da, wählen Sie in seinem Kontextmenü die Funktion generieren und öffnen. Nun wird Ihnen automatisch der gewünschte Inhalt in die Tabellen generiert.

Das Ergebnis sieht so aus:

Die gewünschte Projektdokumentation mit Tabelle in MS Word

Wenn mehrere BlockInterfaces im Package enthalten wären, würden diese jetzt untereinander aufgeführt werden. Das dargestellte Dokument beschränkt sich im Moment auf das in Bild 1 gezeigte grafische Modell.

Und nun sind Sie dran! Vielleicht haben Sie auch ähnliche Fragestellungen aus anderen Ecken Ihrer Modelle und versuchen sich einmal mit Ihrer eigenen Projektdokumentation. Wir sind gespannt auf Ihre Ergebnisse.