Hinweis: Dies ist nur eine kurze Erinnerung für mich selbst und kein vollständiger Artikel. Über dieses Thema lassen sich ganze Bücher schreiben.
Einleitung
Architektur verändert sich im Laufe der Zeit, und die Dokumentation aktuell zu halten ist nicht immer einfach. Das Ergebnis ist eine Beschreibung, die nicht mehr zur tatsächlichen Architektur passt.
Die Probleme
- Architektur entsteht nicht durch eine einzelne Person, sondern über die Zeit durch viele Beteiligte.
- Häufig wird sie weit entfernt vom Quellcode und Repository in Word-Dokumenten oder Wikis wie Confluence dokumentiert.
- Änderungen bleiben dadurch undokumentiert; später ist unklar, welche Informationen noch gültig sind.
- Binärformate wie docx lassen sich schlecht versionieren: Statt einzelner Änderungen sieht man nur eine neue Binärdatei.
Die Lösung
- Änderungen im selben Repository wie den Quellcode dokumentieren.
- Textbasierte Dateien wie Markdown verwenden und daraus die Dokumentation generieren.
- Die Generierung in den Build-Prozess integrieren, etwa mit Gradle oder Maven.
- Ein Änderungsprotokoll entsteht automatisch: Bei Textdateien sind alle Details sichtbar, statt nur eine vollständig ersetzte Binärdatei.
- Vorlagen wie arc42 verwenden und mit projektspezifischen Informationen füllen.
- UML-Diagramme mit PlantUML als Text beschreiben.