Dokumentation als Ballast? Angemessene Dokumentation unterstützt den Austausch im Team und gegenüber Dritten. Ein wirkungsvolles Festhalten der Architektur hilft beim Entwurf der Software, leitet die Umsetzung und führt zu einer nachvollziehbaren und bewertbaren Lösung.
Wie bringen Sie und Ihr Team Ihre Lösungsideen auf den Punkt?
arc42, der etablierte Gliederungsvorschlag für Architekturbeschreibungen, begleitet viele Entwicklungsvorhaben beim Dokumentieren ihrer Softwarearchitektur. Er ist insbesondere in der DACH-Region etabliert.
Mit seinen 12 Abschnitten taugt das arc42-Template in voller Ausbaustufe allerdings nicht als Mindestumfang für einen Architekturüberblick. Auch wenn vieles für seine Verwendung spräche. Es wäre zu groß.
Lassen sich die Grundzüge der Architektur eines Softwaresystems nachvollziehbar auf einem Bierdeckel festhalten?
Die obige Abbildung skizziert einen kompakteren Ansatz in diese Richtung:
Wenn Sie mehr darüber erfahren wollen sei Ihnen ein passender Online-Artikel von unserem Mitarbeiter Stefan Zörner ans Herz gelegt. Die obige Abbildung stammt daraus.
Beispiele für Architekturüberblicke echter Softwaresysteme finden Sie auf unserer Seite über Architekturüberblicke – vom Folienvortrag bis zum Flyer. Unten illustriert durch ein informelles Überblicksdiagramm des mobilen Instant-Messengers Threema aus unserer Reihe “Architektur-Porträts”. Haben Sie Lust bekommen, gemeinsam mit uns und Ihrem Team Ihre Lösungen in dem Stil zu porträtieren? Kommen Sie gerne auf uns zu! (Kontakt)
Docs-as-Code (kurz für “Treat Documentation as Code”) verfolgt die Philosophie, Dokumentation in einem Entwicklungsvorhaben genau so zu behandeln, wie den Quelltext. Das heißt, das Team erstellt, verwaltet und verarbeitet die betreffenden Zutaten, wo immer möglich, mit den gleichen Werkzeugen und auf die gleiche Art und Weise wie Code.
Konkret setzen die Teammitglieder ihren präferierten Texteditor oder ihre gewohnte Entwicklungsumgebung (IDE) ein. Sie speichern die Inhalte in der gleichen Versionsverwaltung wie den Quelltext. Das Team integriert Dokumentation in sein Vorgehen, etwa in Reviews. Es führt diesbezügliche Aufgaben und Fehler in Backlogs und Issue Tracker und integriert die Dokumentation in Build und CI/CD-Pipeline.
