vlaskos/architektur-dokumentations-skill

Softwarearchitekturen dokumentieren

Architekturdokumentation existiert, um Fragen zu beantworten, die Stakeholder Ihnen sonst während der gesamten Lebensdauer des Systems in Meetings stellen würden: Wie ist das zusammengesetzt? Warum ist es so? Wo ändere ich X? Hält es unter Y? Gute Dokumentation beantwortet das einmal, schriftlich, in einer Form, die jeder Leser tatsächlich nutzen kann.

Dieser Skill ist eine Methode, um solche Dokumentation zu erstellen und um Dokumentation zu prüfen, die jemand anders geschrieben hat. Er basiert auf offenen, frei verfügbaren Standards und Modellen, nicht auf einem einzelnen urheberrechtlich geschützten Text:

• ISO/IEC/IEEE 42010 – der internationale Standard für Architekturbeschreibungen. Er liefert das Vokabular, das durchgängig verwendet wird: Stakeholder, Belang, Sichtweise, Sicht, Modell, Architekturentscheidung, Begründung.
• Das C4-Modell (Simon Brown) – eine leichtgewichtige Sammlung von Strukturdiagrammen auf vier Zoomstufen: Kontext, Container, Komponente, Code.
• Das 4+1-Sichtenmodell (Philippe Kruchten) – fünf gleichzeitige Perspektiven: logisch, prozessual, entwicklungsorientiert, physisch und Szenarien, die sie zusammenführen.
• arc42 – eine Creative-Commons-Dokumentationsvorlage, deren Abschnittsstruktur ein praktisches Gerüst für eine vollständige Architekturbeschreibung darstellt.
• Architecture Decision Records (das von Michael Nygard popularisierte ADR-Format) – eine kurze Datei pro bedeutender Entscheidung.

Die Methode

Die Dokumentation wird bestimmt von wer sie liest und was sie entscheiden oder tun müssen. Arbeiten Sie in dieser Reihenfolge.

1. Stakeholder und ihre Belange identifizieren. Listen Sie auf, wer von der Architektur abhängt (Entwickler, Betreiber, Sicherheitsprüfer, Produktverantwortliche, Integratoren, Auditoren) und was die Dokumentation jeweils beantworten muss. Ein Belang ist eine Frage oder Qualität, die für jemanden wichtig ist: „Kann ich das ohne Ausfallzeit ausrollen?“, „Wo leben Kundendaten?“, „Wie füge ich einen neuen Zahlungsanbieter hinzu?“. Belange bestimmen alles, was folgt. Siehe references/viewpoints-and-views.md.

2. Sichtweisen auswählen, die die Belange abdecken. Eine Sichtweise ist eine wiederverwendbare Art von Sicht: die Konventionen zum Erstellen eines Darstellungstyps (welche Elemente sie zeigt, welche Beziehungen, welche Notation). Wählen Sie die kleinste Menge an Sichtweisen, die gemeinsam jeden wichtigen Belang adressieren. Schreiben Sie keine Sicht, die niemand braucht. Siehe references/view-catalog.md.

3. Die Sichten bauen. Jede Sicht ist eine Darstellung des Systems aus einer Sichtweise: ein Diagramm plus die erklärende Prosa. Die meisten Systeme benötigen eine strukturelle Sicht (aus welchen Teilen das System besteht und wie sie voneinander abhängen), eine Laufzeitsicht (was zur Ausführungszeit passiert: Prozesse, Abläufe, Interaktionen) und eine Bereitstellungssicht (wie Software auf Infrastruktur abgebildet wird). Fügen Sie verhaltensorientierte Sichten für die Teile hinzu, bei denen Timing oder Abfolge entscheidend sind. Die C4-Ebenen und die 4+1-Perspektiven sind konkrete, erprobte Wege, diese zu füllen. Siehe references/view-catalog.md.

4. Entscheidungen und ihre Begründung erfassen. Der mit Abstand wertvollste und am häufigsten fehlende Teil der Architekturdokumentation ist das Warum. Halten Sie jede bedeutende Entscheidung (Kontext, betrachtete Optionen, getroffene Wahl und Konsequenzen) als Architecture Decision Record fest. Die Begründung ermöglicht es der nächsten Person, das System sicher zu ändern, anstatt zu raten. Siehe references/decisions-and-rationale.md.

5. Die Beschreibung zusammenstellen und Orientierung hinzufügen. Ein Haufen von Sichten ist kein Dokument. Fügen Sie das verbindende Gewebe hinzu: eine einseitige Systemübersicht, eine Aussage zu Umfang und Kontext, ein Glossar und einen expliziten Hinweis darauf, wie die Sichten zueinander in Beziehung stehen (dasselbe Element, in zwei Sichten gesehen, ist die häufigste Verwirrungsquelle für den Leser – lösen Sie das auf). Verwenden Sie references/documentation-template.md für ein vollständiges Abschnittsschema.

6. Vor dem Versand prüfen. Lassen Sie die Dokumentation gegen references/review-checklist.md laufen. Die beiden Fehlermodi sind Unvollständigkeit (ein Belang, den keine Sicht adressiert) und Unlesbarkeit (Diagramme ohne Legende, undefinierte Begriffe, keine Angabe, was der Leser gerade betrachtet).

Wie man diesen Skill verwendet

• Von Grund auf neu → folgen Sie den sechs obigen Schritten, verwenden Sie references/documentation-template.md als Zielstruktur.
• Entscheiden, was geschrieben werden soll → references/viewpoints-and-views.md (Belänge → Sichtweisen) und references/view-catalog.md (der Katalog der Sichttypen).
• Eine Entscheidung festhalten → references/decisions-and-rationale.md (ADR-Format und Beispiele).
• Vorhandene Dokumente prüfen → references/review-checklist.md.
• Zwischen Frameworks wählen oder eines auf ein anderes abbilden → references/frameworks-map.md.

Grundsätze

• Schreiben Sie für einen Leser, nicht für Vollständigkeit. Jede Sicht, jedes Diagramm und jeder Absatz sollte auf einen Stakeholder-Belang zurückgehen. Wenn Sie nicht benennen können, wer es braucht, streichen Sie es.
• Jedes Diagramm braucht eine Legende. Eine Notation, die „offensichtlich aussieht“, ist es nicht. Geben Sie an, was Kästen und Linien bedeuten. Ein unerklärtes Diagramm ist eine Schätzung, die schiefgehen wird.
• Halten Sie die Begründung fest, während Sie vorgehen. Entscheidungen sind im Moment ihrer Fällung günstig zu erfassen und später teuer zu rekonstruieren.
• Halten Sie es nah am Code und aktuell. Dokumentation, die von der Realität abweicht, ist schlimmer als keine, weil ihr vertraut wird. Bevorzugen Sie ein kleineres Dokument, das Sie pflegen werden, gegenüber einem großen, das Sie nicht pflegen werden.
• Lassen Sie das Risiko des Systems die Tiefe bestimmen. Dokumentieren Sie die Teile, bei denen ein Fehler teuer wäre, detailliert; skizzieren Sie den Rest.