© Liashko/Shutterstock.com
Entwickler Magazin
Leichtgewichtig bleiben mit Markdown, Git und Co.

Architekturdokumentation

Wohl jeder kennt die Situation: Ein neues Projekt startet, und diesmal wollen wir alles richtig machen. Wir machen uns erste Gedanken über die Architektur des Systems und schreiben unsere Ideen auf. Wir halten fest, was wir mit welchen Technologien, Mustern, Prinzipien, Konzepten etc. lösen wollen. Dazu verwenden wir Word oder unser Wiki. Am Anfang klappt auch alles super. Die ersten Änderungen, die sich während der Entwicklung ergeben, schaffen es noch in die Dokumentation. Doch je älter das Projekt wird und je größer das Team, desto seltener werden Änderungen an der Architektur in der Dokumentation nachgezogen. So passiert am Ende genau das, was wir vermeiden wollten: Die Dokumentation unserer Architektur spiegelt nicht die Realität wider und keiner weiß so genau, welche Teile noch richtig sind und welche nicht mehr.

Peter Götz, Stefan Zörner


Warum wird Architektur oft nicht nachhaltig dokumentiert? Softwarearchitektur entsteht heute oft im Team, selten im Kopf eines Einzelnen. Sie wird geprägt durch weitreichende Entscheidungen, etwa zur Strukturierung des Systems oder zur Technologie- und Frameworkauswahl. Architekturdokumentation sollte diese Lösungsansätze nachvollziehbar festhalten, unterstützen beim Entwurf des Systems, bei der Kommunikation im Team und gegenüber Dritten bei der Umsetzung im Code. Über den Sinn und Zweck guter Architekturdokumentation herrscht weitgehend Einigkeit. Sie erleichtert die Einarbeitung neuer Kollegen ins Team und erklärt Zusammenhänge, die sich aus dem Quellcode oft nicht ergeben. Trotzdem wird sie oft stiefmütterlich behandelt und nicht nachhaltig gepflegt. Dafür gibt es unserer Erfahrung nach mehrere Gründe.

So legen viele Teams Architekturdokumentationen in Dokumenten ab, die weit vom Quellcode entfernt sind, beispielsweise in Word-Dateien auf einem Projektverzeichnis oder einem Wiki. Der Entwickler übersieht dann schnell, dass nach einer grundlegenden Änderung der Anwendung auch die Dokumentation der Architektur anzupassen wäre.

Ebenso möglich ist eine unklare Aufgabenverteilung. Zu Beginn eines Projekts ist das Erstellen der Architekturdokumentation oft noch eine explizit zugewiesene Aufgabe. Im Verlauf der Entwicklung fehlt dann oft das Bewusstsein, dass nicht nur Code angefasst werden muss, sondern auch Dokumentation.

Und nicht zuletzt liegt es oft auch daran, dass für die Dokumentation binäre Dateiformate verwendet werden, mit denen es schwierig bis unmöglich ist, Versionen sauber zuzuordnen und gegeneinander zu vergleichen. Oder das Wiki führt zwar Seitenhistorien, aber keine Versionen über alle Seiten hinweg. Das macht die nachhaltige Pflege der Architekturdokumentation zu einer mühsamen Tätigkeit, der man lieber aus dem Weg geht.

Architektur näher an die Umsetzung bringen

Um eine Architekturdokumentation zu strukturieren, empfehlen sich leichtgewichtige Gliederungsvorschläge, die zugleich etwas Orientierung beim Entwurf des Systems bieten. Das Software Guidebook von Simon Brown [1] ist ein schlankes Beispiel dazu, im deutschsprachigen Raum hat sich arc42 von Gernot Starke und Peter Hruschka [2] als Quasistandard etabliert. arc42 stellt eine hervorragende Vorlage für die Dokumentation von Architekturen dar und wird in verschiedenen Formaten angeboten, z. B. als .docx-Datei oder Confluence Space.

Wir nutzen die arc42-Struktur als Beispiel, um Architek...

Entwickler Magazin
Leichtgewichtig bleiben mit Markdown, Git und Co.

Architekturdokumentation

Wohl jeder kennt die Situation: Ein neues Projekt startet, und diesmal wollen wir alles richtig machen. Wir machen uns erste Gedanken über die Architektur des Systems und schreiben unsere Ideen auf. Wir halten fest, was wir mit welchen Technologien, Mustern, Prinzipien, Konzepten etc. lösen wollen. Dazu verwenden wir Word oder unser Wiki. Am Anfang klappt auch alles super. Die ersten Änderungen, die sich während der Entwicklung ergeben, schaffen es noch in die Dokumentation. Doch je älter das Projekt wird und je größer das Team, desto seltener werden Änderungen an der Architektur in der Dokumentation nachgezogen. So passiert am Ende genau das, was wir vermeiden wollten: Die Dokumentation unserer Architektur spiegelt nicht die Realität wider und keiner weiß so genau, welche Teile noch richtig sind und welche nicht mehr.

Peter Götz, Stefan Zörner


Warum wird Architektur oft nicht nachhaltig dokumentiert? Softwarearchitektur entsteht heute oft im Team, selten im Kopf eines Einzelnen. Sie wird geprägt durch weitreichende Entscheidungen, etwa zur Strukturierung des Systems oder zur Technologie- und Frameworkauswahl. Architekturdokumentation sollte diese Lösungsansätze nachvollziehbar festhalten, unterstützen beim Entwurf des Systems, bei der Kommunikation im Team und gegenüber Dritten bei der Umsetzung im Code. Über den Sinn und Zweck guter Architekturdokumentation herrscht weitgehend Einigkeit. Sie erleichtert die Einarbeitung neuer Kollegen ins Team und erklärt Zusammenhänge, die sich aus dem Quellcode oft nicht ergeben. Trotzdem wird sie oft stiefmütterlich behandelt und nicht nachhaltig gepflegt. Dafür gibt es unserer Erfahrung nach mehrere Gründe.

So legen viele Teams Architekturdokumentationen in Dokumenten ab, die weit vom Quellcode entfernt sind, beispielsweise in Word-Dateien auf einem Projektverzeichnis oder einem Wiki. Der Entwickler übersieht dann schnell, dass nach einer grundlegenden Änderung der Anwendung auch die Dokumentation der Architektur anzupassen wäre.

Ebenso möglich ist eine unklare Aufgabenverteilung. Zu Beginn eines Projekts ist das Erstellen der Architekturdokumentation oft noch eine explizit zugewiesene Aufgabe. Im Verlauf der Entwicklung fehlt dann oft das Bewusstsein, dass nicht nur Code angefasst werden muss, sondern auch Dokumentation.

Und nicht zuletzt liegt es oft auch daran, dass für die Dokumentation binäre Dateiformate verwendet werden, mit denen es schwierig bis unmöglich ist, Versionen sauber zuzuordnen und gegeneinander zu vergleichen. Oder das Wiki führt zwar Seitenhistorien, aber keine Versionen über alle Seiten hinweg. Das macht die nachhaltige Pflege der Architekturdokumentation zu einer mühsamen Tätigkeit, der man lieber aus dem Weg geht.

Architektur näher an die Umsetzung bringen

Um eine Architekturdokumentation zu strukturieren, empfehlen sich leichtgewichtige Gliederungsvorschläge, die zugleich etwas Orientierung beim Entwurf des Systems bieten. Das Software Guidebook von Simon Brown [1] ist ein schlankes Beispiel dazu, im deutschsprachigen Raum hat sich arc42 von Gernot Starke und Peter Hruschka [2] als Quasistandard etabliert. arc42 stellt eine hervorragende Vorlage für die Dokumentation von Architekturen dar und wird in verschiedenen Formaten angeboten, z. B. als .docx-Datei oder Confluence Space.

Wir nutzen die arc42-Struktur als Beispiel, um Architek...

Neugierig geworden?


   
Loading...

Angebote für Teams

Für Firmen haben wir individuelle Teamlizenzen. Wir erstellen Ihnen gerne ein passendes Angebot.

Das Library-Modell:
IP-Zugang

Das Company-Modell:
Domain-Zugang