embarc logo
embarc logo

Zeitgemäße Dokumentationsansätze

Vom prägnanten Architekturüberblicken, Docs-as-Code & Co.

 
 
 

Lösungsansätze festhalten und kommunizieren

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.

 

Prägnante Architekturüberblicke

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?

Architekturüberblick auf einem Bierdeckel
Architekturüberblick auf einem Bierdeckel

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)

Informeller Überblick über den mobilen Instant-Messenger Threema (Gesamtsystem)
Informeller Überblick über den mobilen Instant-Messenger Threema (Gesamtsystem)

 

Docs-as-Code

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.

Docs-as-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.

Nützliche Publikationen, Vortragsmitschnitte und Downloads

Softwarearchitekturen dokumentieren cover
Stefan Zörner: Softwarearchitekturen dokumentieren und kommunizieren Entwürfe, Entscheidungen und Lösungen nachvollziehbar und wirkungsvoll festhalten
Hanser Fachbuch, 3., überarbeitete und erweiterte Auflage (Dez. 2021), 309 Seiten. Fester Einband
ISBN: 978-3-446-46928-0
Webseite: www.swadok.de
Weitere Themen...