Dokumentieren für Architekturbeteiligte

Softwarearchitekturen dokumentieren und kommunizieren

CoverDas Buch ist erfreulich dünn, keine schwere Schwarte. Es stellt sowohl dar, wo es Probleme gibt, wenn die Dokumentation vernachlässigt wird, als auch den Benefit einer angemessenen Doku und in welchen Fällen eine gute Doku dem Team hilft. Außerdem verrät es, wie man lästigen Overhead beim Erstellen und Pflegen minimiert.

Beim Nachvollziehen hilft der rote Faden, um die Notwendigkeit von Dokumentation klar zu machen: Ein neuer Kollege versucht sich ins Entwicklungsprojekt einzufinden, mit dem Wunsch, schnell selbst produktiv sein zu können.

Ganz nach Belieben ist das Buch auch als reines Nachschlagewerk geeignet. Die Abschnitte lassen sich gut und schnell lesen, durch einen flüssigen Schreibstil und eine übersichtliche Gliederung. Nützlich auch, dass es zum physischen Exemplar auch gleich das E-Book dazu gibt (ISBN 978-3-446-43128-7 beim „ebookinside“ nach Registrieren als Kunde in einer Onlineansicht oder als PDF von 8,8 MB).

Der Autor bietet an, ihm per Email als PDF eigene Lösungsvorschläge zu den Übungen zu schicken, um die Musterlösung zugeschickt zu bekommen und – jetzt kommt’s – zur eigenen Lösung individuell Rückmeldung zu geben (wenn er die Zeit dazu findet). Ich hab’s nicht ausprobiert, aber vielleicht versucht Ihr es mal? (Den Erfahrungsbericht oder eine kurze Meldung nehm ich natürlich gern entgegen.)

Schnell zu finden und anzupassen sind die vorgestellten „Dokumentationsmittel“ in form von Steckbriefen, wie was beschrieben werden kann (z. B. Dokumentation des Systemkontextes). Dazu gibt es kurze, praktische Beispiele, wie so ein Dokumentationsmittel konkret aussehen kann. Ein weiterer Abschnitt erklärt, wie Entscheidungen gefunden und dokumentiert werden können – nicht nur für Architektinnen interessant!

Abschließend liefert der Autor eine Beschreibung der typischen Stolpersteine und wie man ihnen begegnet, u. a. mit Unterstützung durch Reviews der Dokumentationsergebnisse (d. h. Begutachten durch Unbeteiligte).

Überzeugend ist die Liebe zum Detail, es gibt u. a. Tipps, wie man Fragestellungen identifiziert, aufstellt, findet und formuliert. Am Ende gibt es eine grafische Darstellung der Themen, Begriffe und deren Zusammenhang, hier als Einleitung zum üblichen Glossar.

Fazit: Hilfreich, nicht nur für Architektur

Themen

  • Qualitätsziele
  • Stakeholder und Persona
  • Entscheidungen finden
  • Verschiedene Sichten
  • Übergreifende Konzepte
  • Dokumentationswerkzeuge
  • Wann dokumentieren: verschiedene Varianten
  • Fallbeispiel DokChess (Schachspielplattform online)
  • Reviews
  • Motivation: wozu überhaupt Architektur dokumentieren
  • Grundlagen, Aufbau, mögliche Gliederung

Website zum Buch mit Vorlagen (z.  B. die Mindmap für einen Qualitätsbaum als Datei für MindManager, Werkzeugen, Links):
www.swadok.de

Stefan Zörner: „Softwarearchitekturen dokumentieren und kommunizieren. Entwürfe, Entscheidungen und Lösungen nachvollziehbar und wirkungsvoll festhalten“. Hanser 2012. 34,90 EUR (D). ISBN 978-3-446-42924-6.

Augen-Logo Maria

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.