Software-Architektur Dokumentation

Die Software-Architektur Dokumentation dient vor allem diesen Zielen:

• Eine schnelle und effektive Entwicklung ermöglichen
• Das Entwicklungsprojekt —Zeiten, Ressourcen — präzise planen
• Die regulatorischen Anforderungen an die Software-Architektur erfüllen
• Die Weiterentwicklung des Systems und die Einarbeitung neuer Mitarbeiter erleichtern

Eine schnelle, effektive und planbare Software-Entwicklung wird v.a. dann gelingen, wenn man die Aufgabe (eine Software zu entwickeln, die den Software-Anforderungen genügt) in lösbare Teilaufgaben zerlegt und diese Teilaufgaben auf viele Entwickler verteilen kann.

Die Voraussetzung dafür ist eine präzise (Dokumentation der) Software Architektur, die leiderin vielen agilen Software-Entwicklungsprojekte zu kurz kommt.

Regulatorische Anforderungen an die Software-Architektur Dokumentation

Sowohl die IEC 62304 als auch die FDA fordern eine dokumentierte Software-Architektur, wobei die Forderungen der FDA über die der IEC 62304 hinausgehen. Letztere fordert eine Software-Architektur nur für Software-Systeme der Sicherheitsklassen B und C.

Anmerkung: Auch wenn die IEC 62304 für die Software-Sicherheitsklasse A keine Software Architektur vorsieht, so wird das Erstellen einer Software-Architektur als Stand der Technik in der Software-Entwicklung angesehen und ist zumindest im Kontext der IT-Sicherheit gefordert (siehe IEC 81001-5-1). 

Forderungen der IEC 62304

Wenn Sie eine Software-Architektur dokumentieren und lediglich die Forderungen der IEC 62304 erfüllen wollen, müssen sie wenig beachten. Denn diese Norm verlangt im Wesentlichen nur fünf Dinge:

1. Software-Komponenten identifizieren
2. Schnittstellen zwischen Komponenten beschreiben
3. SOUPs identifizieren, Anforderungen daran beschreiben
4. Komponenten klassisifizieren (Default: Klasse C)
5. Rückverfolgbarkeit (Traceability) sicherstellen

Forderungen der FDA

Die FDA fordert bei der Software-Architektur darüber hinaus auch eine Beschreibung bzw. Modellierung des dynamischen Verhaltens wie man das üblicherweise mit Sequenz- oder Aktivitätsdiagrammen modelliert. Aber auch hier sollte das innere Verhalten der Software beschrieben werden, nicht das externe. Das ist ein Aspekt der Software-Anforderungen.

Beachten Sie, dass die FDA bei beiden „documentation level“ eine Einreichung der Software-Architektur verlangt. Nach den neuesten FDA-Richtlinien von 2023 muss der Antrag immer eine Softwarearchitektur enthalten.

Gedanken zu den Anforderungen an die Software-Architektur Dokumentation

Die regulatorischen Anforderungen an die Dokumentation einer Software-Architektur sind nur Minimalanforderungen und keine Best Practices: Eine Software zu beschreiben, ohne die dynamische Sicht zu beachten, erscheint als etwas zu „dünn“. Eine Software-Architektur ist dann gelungen, wenn

• ein Programmierer daraus ohne große Rückfragen stellen (d.h. ohne ad-hoc Design-Entscheidungen treffen) zu müssen, daraus das Produkt entwickeln kann
• und alle Anforderungen damit erfüllt werden können.

Beachten Sie: In einem professionellen Team findet die eigentliche Wertschöpfung beim (gemeinsamen) Denken und Diskutieren d.h. beim Entwerfen der Software-Architektur und nicht beim Kodieren statt!

Ein Auditor wird aber nur die Güte der Software-Architektur Dokumentation prüfen, nicht die Güte der Software-Architektur selbst.

Aufbau der Software-Architektur Dokumentation

Gliederung

Sie können das Software-Architektur Dokument gemäß folgender Kapitelstruktur gliedern:

1. Metainformationen (z.B. Autor, System, Version, Datum, Ziel)
2. Executive Summary
3. Kontextabgrenzung
4. Bausteinsicht
5. Dynamische Sicht
6. Verteilungssicht
7. Querschnittsaspekte
8. Entwurfsentscheidungen
9. Risikomanagement und Sicherheitsklassifizierung
10. Anhänge

Hinweis: Als Richtschnur, für eine „gute“ Dokumentation von Software-Architekturen empfehlen sich die ISO/IEC 42010 (guter Wikipedia-Artikel) und das Template von arc42.

Bausteinsicht

Mit das wichtigste Kapitel in der Software-Architektur Dokumentation ist die Bausteinsicht, die die statische oder logische Struktur im Sinne beschreibt. Aus regulatorischer Sicht sollten Sie zumindest die ersten beiden Hierarchieebenen des Komponentenbaums beschreiben, in nachfolgender Abbildung die blauen und grünen „Kästchen“.

Sie haben zumindest zwei Möglichkeiten, dieses  Kapitel in der Software-Architektur Dokumentation zu strukturieren:

Variante 1

1. Subsystem A
   1. Modul A1
   2. Modul A2
   3. Modul A2
2. Subsystem B
   1. Modul B1
   2. Modul B2
   3. Modul B3
3. Subsystem C
   1. Modul C1
   2. Modul C2
   3. Modul C3
   4. Modul C4

Variante 2

1. Bausteinebene 1
   1. Subsystem A (Blackbox)
   2. Subsystem B (Blackbox)
   3. Subsystem C (Blackbox)
2. Bausteinebene 2
   1. Subsystem A (Whitebox)
      1. Modul A1 (Blackbox)
      2. Modul A2 (Blackbox)
      3. Modul A2 (Blackbox)
   2. Subsystem B (Whitebox)
      1. Modul B1 (Blackbox)
      2. Modul B2 (Blackbox)
      3. Modul B3 (Blackbox)
   3. Subsystem 3 (Whitebox)
      1. Modul C1 (Blackbox)
      2. Modul C2 (Blackbox)
      3. Modul C3 (Blackbox)
      4. Modul C4 (Blackbox)

Umfang der Software-Architektur Dokumentation

Modellieren Sie „nur“ so genau, dass Sie keine adhoc Design-Entscheidungen mehr treffen müssen. Lieber ein kurzes und präzises Dokument als ein episches Werk, das keiner liest und auch nicht mehr aktuell ist.

40-50 Seiten ist eine gute Faustformel für den Umfang der Dokumentation Ihrer Software-Architektur. Das erreichen Sie dann, wenn Sie mit Bildern statt mit umfangreichen Texten arbeiten.

Wenn Sie Dinge genauer beschreiben wollen oder müssen, dann lagern Sie beispielsweise die Komponenten / Subsystem-Spezifikationen in eigenständige Dokumente  aus. Das empfehle ich besonders dann, wenn Sie diese Subsysteme oder Komponenten in anderen Software-Systemen oder Produkten ebenfalls verwenden.

Wünschen Sie Unterstützung dabei, Ihre Software-Architektur schnell, präzise und normenkonform zu dokumentieren, um eine wartbare Software in „Time & Budget“ entwickeln zu können? Professor Johner und sein Team helfen gerne! Nehmen Sie Kontakt auf!