Viele von uns kennen das Tool „Enterprise Architect“ als Designwerkzeug zur Erstellung von Software Architekturen. Für alle, die die den EA noch nicht kennen, sei folgender Link empfohlen: Getting started with Enterprise Architect auf YouTube.

Gut sind auch seine Möglichkeiten zur Planung und Erstellung der kompletten Dokumentation von Software Projekten. Auf diese Optionen möchte ich hier besonders hinweisen!

In Software Projekten wird die Dokumentation meist etwas stiefmütterlich behandelt. Der praxisnahe Grund: Es soll in knapp bemessener Zeit ein hochwertiges Software Produkt erstellt werden.

Und dabei entstehen folgende Konflikte:

  • die kontinuierliche Aktualisierung erstellter Dokumente (mit unterschiedlichen Tools und Formaten)
  • der Anspruch auf Vollständigkeit bezüglich
    • Nachweis des SW Entwicklungsprozess, V Modell,
    • Use Cases,
    • System Architektur und SW Architektur,
    • SW Design,
    • Datenfluss,
    • Memory Management,
    • Angaben zum Runtime-Measurement,
    • Tasks-Management,
    • Interrupt Handling,
    • Scheduling,
    • Traceability,
    • Diagnosekonzept,
    • Debugging Konzept,
    • Testkonzept,
    • Configuration Management,
    • Qualitätsmanagement,
    • Safety Aspekte,
    • spezielle Aspekte HW-naher Programmierung,
    • Informationen zum eingesetzten Microcontroller etc.
  • praktikable Zugänglichkeit zu Dokumenten verschiedenster Quellen und Formate, die die Vollständigkeit der oben aufgelisteten Themen gewährleisten sollen
  • angemessene Beschreibungstechniken der aufgelisteten Aspekte

Gründe, die zu unzureichender Dokumentation führen, sind

  • terminlich enggeplante Milestones, die sich auf schnell vorzeigbare Applikationen konzentrieren, um die Kunden zufrieden zu stellen,
  • die bei den Entwicklern häufig (unterschwellig) anzutreffende Ansicht, dass der Arbeitsfortschritt davon behindert wird,
  • Vermutung, dass die Offenlegung des Knowhows die Konkurrenz erfreut und der Marktstellung des Unternehmens/dem Entwickler langfristig schadet,
  • die gefühlt monotone Dokumentationsarbeit mit wenig Erfolgserlebnissen (zumal das Wissen ja bereits im eigenen Kopf vorhanden ist),
  • die häufig sehr knapp bemessene Zeit für den Projektabschluss, in der die Dokumentation auf den letzten Stand gebracht werden soll,
  • der Einsatz verschiedenster Tools zur Erstellung der unterschiedlichen Dokumentationen, was die Übersicht über Stand und Konsistenz zwischen den Dokumentationen erschwert,
  • sowie die nicht unerheblichen Kosten für (Dokumentations-)Tools (+ ggf. Schulung und Lizenzen).

Vorteile des Einsatzes des Enterprise Architect:

  • pragmatischer Ansatz
    • die im Laufe des Projekts entstehenden internen und externen Dokumente, ob Texte oder Grafiken, werden an zentraler Stelle per interner/externer Verlinkung zu Repositories gebündelt und zugänglich gemacht
  • schneller Zugang zu allen wichtigen Systeminformationen
    • ein einheitlicher Zugang erleichtert die Einarbeitung neuer Mitarbeiter in das Projekt
  • Gliederung der Informationen in Packages
    • erlaubt die Sammlung spezifischer Aspekte für die Entwicklung bzw. für Wartung
  • Status des Projektes
    • läuft die Dokumentation mit der Entwicklung so gut wie nötig parallel mit, erhält man stets einen belastbaren Stand der Entwicklung
  • Informationen zur Unterstützung in projektbezogenen Audits
    • wie z.B. der Nachweis von End2End Traceability (lückenlose Rückverfolgbarkeit von Anforderungen, Analyse und Design-Modellen bis hin zur Dokumentation in der Implementierung)
    • relativ einfache Verlinkung der importierten Anforderungen aus System und SW zu den (aus verschiedenen Quellen verlinkten) Dokumenten sowie zu den UML-Modellen/Diagrammen sind im Tool selbst erzeugbar
    • das gilt insbesondere auch für die nicht-funktionalen Anforderungen, die ja nicht unmittelbar auf Diagramme/konkrete Elemente der SW-Architektur referenziert werden können
  • Rollenbasierte Zugangsrechte
    • Konfigurierbare Editierbarkeit von Elementen für Einzelperson/Gruppe
  • Team Review
    • über ein Messagesystem können Einzelperson/Gruppe zum Review einzelner Elemente eingeladen werden bzw. ihre Beiträge posten
  • Generierung von Dokumenten ist möglich
    • Unterstützung der Formate PDF, DOCX, RTF
    • auf Package-Ebene, in verschiedenen formalen Ausprägungen
  • das Tool selbst ist relativ kostengünstig
  • für die Nutzung als Dokumentationstool ist der Schulungsaufwand überschaubar

Um dem Ziel der Bündelung aller wesentlichen Dokumente zum SW-Projekt näher zu kommen,
ist es zielführend, sich im ersten Schritt firmenübergreifend auf einen Dokumentations-Mindeststandard im EA zu einigen. Dazu gehören die Auflistung aller zu dokumentierenden Aspekte, basierend auf den Artefakten, die im SW Projekthandbuch festgelegt sind. Hierzu kann das MindMap-Feature des Tools nützlich sein. (Für kurzlebige Informationen nutzt man sinnvollerweise firmeninternen Wikis.)
Weiterhin sind Festlegungen zur Breite, Tiefe und Vollständigkeit der Informationsaufnahme, Beschreibung von Ausnahme- und Sonderfällen sowie formale Punkte wie einzubindende Formate, Verlinkung externer Artefakte u. ä., zu regeln.

Im zweiten Schritt kann man sich der Dokumentationsgenerierung widmen. Das Tool bietet die Erstellung von Templates an, die der Generierung von Dokumentation mit projekt- und kundenspezifischen Layouts dienen. Unterschieden werden Templates für

  • Cover Page,
  • Table of Content,
  • Packages,
  • Elements,
  • und Tables.
  • Es gibt auch die Möglichkeit Stylesheets einzusetzen.

Wesentlich für den Erfolg sind folgende Aspekte

  • die Qualität verbessert sich spürbar, wenn man die Dokumentation parallel zum Software Entwicklungsprozess plant und durchführt
  • um die Akzeptanz des Tools stärken, muss Zeit zur kontinuierlichen Überprüfung der Konsistenz eingeplant werden
  • der Zugang zum Tool und die Vorgehensweise muss für alle Beteiligten bereits von Projektbeginn an bekannt und möglich sein, um allgemein die Akzeptanz der Vorgehensweise zu stärken und möglichst wenig Informationsverluste zu erzeugen
Autor: Ricarda Marzillier, Thomas Keese