embarc logo
embarc logo

Bestehendes nachdokumentieren

Halten Sie Ihre Architekturansätze und Ideen wirkungsvoll fest, anstatt sie zu vergessen! Fördern Sie die Kommunikation innerhalb der Entwicklung und binden Sie Kunden, Fremdprojekte und neue Teammitglieder einfacher ein.

 
 

Was erwartet Sie?

In der Theorie entsteht Architekturdokumentation bereits während des Entwurfes. Die Projektrealität sieht oft anders aus. Ihre auch? Wir unterstützen Sie dabei, im nachhinein eine passende Architekturdokumentation oder zumindest einen vorzeigbaren Überblick anzufertigen. Ganz pragmatisch und effizient.
Details

Steckbrief

Unser Angebot
Wir legen mit Ihnen die Basis für eine leichtgewichtige Dokumentation Ihrer bestehenden Softwarearchitektur. Dazu ermitteln wir gemeinsam die Zielgruppen und deren Informationsbedürfnisse und identifizieren die passenden Zutaten und Werkzeuge. Anschließend fertigen wir mit Ihnen erste Fassungen an.
Unsere Expertise
Stefan Zörner hat aktiv zu arc42 beigetragen und bereits 2012 mit seinem Buch “Softwarearchitekturen dokumentieren und kommunzieren” (Hanser-Fachbuch, 3. Auflage 2021) das deutschsprachige Standardwerk zum Thema vorgelegt. Heute verantwortet er als Kurator den einschlägigen iSAQB Advanced-Lehrplan (ADOC). Architektur-Porträts prominenter Softwaresysteme wie Spring oder Visual Studio Code teilen wir als praxistaugliches Anschauungsmaterial regelmäßig und gern.
Typische Anlässe
Das Anfertigen einer Architekturdokumentation ist dringend geboten, wenn wichtige Know-how-Träger das Vorhaben oder Unternehmen verlassen (“Brain Drain”). Aber auch, wenn Lösungsansätze und Konzepte der Architektur eine breitere Anwendung finden oder grundlegende Architekturideen trotz Freiheiten in den Teams eingehalten werden sollen (“Microservices”). Auch wenn ein technischer Proof of Concept mit einem größeren Team fachlich umgesetzt werden soll oder eine Architekturvision an Entscheider und andere Projektfremde zu vermitteln ist.
Ihr Nutzen
Dokumentation unterstützt Kommunikation. Unsere Expertise in diesem Bereich kommt in vielen unserer Einsätze zum Tragen. Unsere Berater:innen sind exzellent im Vermitteln von Wissen und Methoden. Sie befähigen Ihr Team in kurzer Zeit und gebrauchstaugliche Dokumentation anzufertigen. Mit ihr binden Sie Kunden, Fremdprojekte und neue Teammitglieder einfacher ein.

Vorgehen

Den hier skizzierte Ablauf spielen wir iterativ gemeinsam mit Ihrem Team durch. In einer ersten Iteration entsteht bereits ein prägnanter Architekturüberblick, der die wesentlichen Lösungsansätze nachvollziehbar festhält.
01
Zielgruppen und Ziele identifizieren
Wir identifizieren die Zielgruppen Ihrer Architekturdokumentation und machen deren Intentionen explizit. An wen müssen Sie und Ihr Team ihre Ideen, Entscheidungen und Ergebnisse kommunizieren, und warum? Im Anschluss fokussieren wir auf die maßgeblichen Zielgruppen.
02
Zutaten auswählen und initial anfertigen
Wir entscheiden, welche Dokumentationsmittel (“Zutaten”) für welche Zielgruppe in welcher Tiefe zu erstellen sind. Erste Fassungen erarbeitet Ihr Team Hand in Hand mit unseren Expert:innen. In diesem Zusammenhang wählen wir angemessene Tools für Diagramme und textuelle Inhalte aus.
03
Zutaten in Form bringen
Die Dokumentationsmittel legen wir geeignet in einem Repository, etwa Ihrer Versionsverwaltung, ab. Wir rekombinieren die Zutaten zielgruppengerecht zu prägnanten Dokumenten, Foliensätzen, Flyern usw.
04
Rückmeldungen der Zielgruppen einholen
Eine erste Überprüfung auf Gebrauchstauglichkeit erfolgt gemeinsam mit Vertretern der Zielgruppe(n). Das Feedback fließt in Inhalt und Form Ihrer Architekturdokumentation ein. Wir justieren wir und wiederholen die Schritte wo erforderlich, nehmen weitere Zielgruppen hinzu, ergänzen und vertiefen Inhalte und bereiten diese in weiteren Formen auf.

FAQs

Warum können wir nicht einfach arc42 einsetzen?
arc42 ist ein verbreiteter Vorschlag zur Gliederung von Architekturdokumentation. Gegen den Einsatz spricht erstmal nichts. Gleichzeitig bringt es wenig, arc42 einfach "auszufüllen". So entsteht keine zielgruppengerechte, langfristig gebrauchstaugliche Dokumentation.
Die Dokumentation veraltet ohnehin. Sollten wir uns den Aufwand nicht sparen?
Tatsächlich ist das ein häufiges Problem. Allerdings verhindern bewährte Techniken – richtig angewandt – das Veralten, ohne dass dabei hoher Aufwand entsteht. Die Stichworte lauten Fokussierung und Automatisierung.
Wie lange dauert es, einen kompakten Architekturüberblick für mein System anzufertigen?
Wir können mit Ihrem Team bereits in einem 1-Tages-Workshop erste vorzeigbare Ergebnisse produzieren. Vorausgesetzt das Team, mit dem wir die Inhalte gemeinsam erarbeiten, kennt das System. Archäologische Grabungen und Hochglanzdiagramme erfordern mehr Zeit.
Können wir embarc auch einfach beauftragen, die Dokumentation für uns anzufertigen?
Wir erarbeiten das grundsätzlich gemeinsam mit Ihrem Team. Das ist oft selbst eine der Zielgruppen, zudem steckt viel Wissen in den Köpfen. Wir sichern so ab, dass mit vertretbarem Aufwand vernünftige Ergebnisse entstehen.

Haben wir Ihr Interesse geweckt?

Verwenden Sie das Kontaktformular oder senden Sie unserem Koordinator für diese Leistung, Stefan Zörner, eine E-Mail.