Die Nutzung des Tools zur UML Analyse und als Designwerkzeug für Erstellung von SW Architekturen bzw. in Re-Engineering-Projekten ist allgemein bekannt und weit verbreitet. Es kann aber auch dazu dienen, sich des leidigen „Stiefkinds“ Dokumentation, speziell der Systemdokumentation für Entwickler bzw. spätere Wartung, an zentraler Stelle anzunehmen. Mögliche Einsatzgebiete sind Angebotserstellungen eigener SW-Produkte, aber auch Dienstleistungsprojekte.

Mitarbeiter in SW-Projekten kennen den „ewigen Widerspruch“ bei der Abwicklung von SW-Projekten: In kürzester Zeit soll ein qualitativ hochwertiges SW-Produkt erstellt werden. Passend dazu wird eine qualitativ ausreichende, gute Dokumentation erwartet, die den Ansprüchen für Weiterentwicklung und Wartung entspricht.

Typische Reibungspunkte sind der Kampf um…

  • die kontinuierliche Aktualisierung erstellter Dokumente (mit unterschiedlichen Tools und Formaten)
  • Vollständigkeit bezogen auf:
    • Nachweis des SW Entwicklungsprozess
    • V Modell
    • Use Cases
    • System-und SW Architektur
    • SW Design
    • Datenfluss
    • Memory Management
    • Angaben zum Runtime-Measurement
    • Tasks-Management
    • Interrupthandling
    • Scheduling
    • Traceability
    • Diagnosekonzept
    • Umsetzung von Möglichkeiten des Debugging
    • Testkonzept
    • Configuration Management
    • Qualitätsmanagement
    • Safety
    • spezielle Aspekte HW-naher Programmierung
    • Informationen zum eingesetzten Microcontroller etc.
  • praktikable Zugänglichkeit zu Dokumenten verschiedenster Quellen und Formate
  • angemessene Beschreibungstechniken der aufgelisteten Aspekte

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

  • terminlich eng geplante 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.
  • die Vermutung, dass die Know-How-Offenlegung die Konkurrenz erfreut und der Markstellung 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.
  • die nicht unerheblichen Kosten für (Dokumentations-)Tools (+ ggf. Schulung und Lizenzen).

Vorteile des Einsatzes des Enterprise Architect:

  • pragmatischer Ansatz
    Die im Laufe der 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
    Sie 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.
  • auditierbare Informationen
    Wie z.B. der Nachweis von End-To-End Traceability (lückenlose Rückverfolgbarkeit von Anforderungen, Analyse und Design-Modellen bis hin zur Dokumentation in der Implementierung).
    Relativ einfache Verlinkung der importierten Requirements 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 firmeninterne Wikis.)
Weiterhin sind Festlegungen zur Breite, Tiefe und Vollständigkeit der Informationsaufnahme, Beschreibung von Ausnahme- und Sonderfällen sowie formale Punkte wie einbindbare 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
  • 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 Entwicklungsprozess plant und durchführt.
  • Um die Akzeptanz des Tools zu stärken, muss Zeit zur kontinuierlichen Überprüfung der Konsistenz eingeplant werden.
  • Der Zugang zum Tool und die Vorgehensweise müssen 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