Automatisierte Dokumentation eines kritisches Industriesystems

Bei dem Projekt Nachdokumentation handelt es sich um die Erstellung der ordnungsgemäßen Dokumentation eines kritischen Industriesystems. In einer ersten Analyse wurden Lücken in der Dokumentation und Transparenz des Kerns der Systeme identifiziert.

Zu diesem Zweck wird aus dem vorhandenen Source-Code sowohl automatisiert als auch manuell eine funktionale, technische Dokumentation gewonnen. Zeitgleich werden Interviews und Workshops durch die Firma Sysparency durchgeführt, um die funktionale Dimension zu erheben und anschließend die technischen und funktionalen Erkenntnisse zu korrelieren und strukturieren. 

Die Lösung

Arten der Dokumentationserstellung:

Die semi-automatische Dokumentation erfolgt durch die Sysparency Software. Die Ergebnisse sind mathematische Dokumentationen der funktionalen Logik, systeminterne/-externe API-Dokumentation, Klassendiagramme inklusive Vererbungen. Dieser Prozess wird semi-automatisch durchgeführt, da es bei der Umwandlung in mathematische Formeln und strukturierte Inhalte manueller Prüfungen und Definitionen bedarf.  Diese Ergebnisse haben sowohl technische, wie auch fachlich Relevanz auf die Vorgehensweise und Aufwände in der Nachdokumentation. Die manuelle Dokumentationserstellung beinhaltet klassische Methoden des Requirements Engineering, wie die Sichtung existierender Unterlagen zur relevanten Thematik, die Aufbereitung und Konsolidierung von unterschiedlichen Ergebnistypen, wie z.B.: die Aufbereitung der fachlichen Workshops bzw. iterativen Feedbackschleifen mit Experten seitens des Auftraggebers.   Sysparency organisiert und steuert in Abstimmung mit den internen, verantwortlichen Mitarbeitern aus den Entwicklungs und -Fachbereichen sowie dem Projekt Nachdokumentation eigenständig die Erstellung der Dokumentation.  

Erläuterungen zur semi-automatisierten Dokumentation

Die semi-automatisierte Dokumentation wird auf jene Softwareteile angewandt, in denen mathematische und technische Kernstücke der Software codiert sind. Für die semi-automatisierte Erstellung von Entwicklerdokumentation wird das Tool Sysparency eingesetzt. Sysparency analysiert den Quellcode der zu dokumentierenden Software, identifiziert dokumentationsrelevante Informationen und überführt (transformiert) diese in eine hochqualitative Dokumentation. Struktur und Inhalt der Dokumente entsteht im Wesentlichen in drei Schritten. Erstens identifiziert Sysparency mathematische Berechnungen im Quellcode und extrahiert diese in Form von Formeln, Entscheidungstabellen und ggf. Funktionsplots.  Zweitens analysiert Sysparency die im Quellcode vorhandenen Kommentare, ordnet diese durch eine regelbasierte Kategorisierung den extrahierten Formeln etc. zu und überträgt die Ergebnisse in das resultierende Dokument. Im letzten Schritt werden durch compilertechnische Programmanalysen (z. B. Steuer- und Datenfluss) extrahierte Informationen strukturiert und damit die endgültige Struktur der generierten Dokumente festgelegt.  Ein auf diese Weise erzeugtes Dokument beinhaltet Listen der einzelnen Funktionalitäten (anhand der Implementierung) zusammen mit einer Kurzbeschreibung, geprüfte Vorbedingungen, zusammengefasste Ablaufbeschreibungen und mathematische Funktionen der einzelnen Funktionalitäten. Die generierten Dokumente werden ggf. manuell nachbearbeitet und mit weiteren Dokumenten (z. B. API-Dokumentation) verlinkt. Die funktionale Sicht und Informationen werden im Zuge von Workshops mit den verantwortlichen Know-How Trägern erhoben und durch Sysparency ergänzt. Die Vor- & Nachbereitung, sowie die Moderation dieser Workshops übernehmen Sysparency Experten. Im Anschluss der Workshops werden die Informationen in die Dokumentation überführt und strukturiert eingearbeitet.