Dokumentation & ADRs - Archyl Docs

Erstellen und verwalten Sie Architekturdokumentation und Architecture Decision Records in Archyl

Dokumentation & ADRs

Archyl bietet leistungsstarke Dokumentationsfunktionen, mit denen Sie umfangreiche, verknüpfte Dokumentation neben Ihren Architekturdiagrammen erstellen können. Halten Sie Ihr Architekturwissen organisiert und verbunden.

Dokumentation erstellen

Manuelle Dokumentation

Um Dokumentation manuell zu erstellen:

  1. Gehen Sie zum Docs-Tab in Ihrem Projekt
  2. Klicken Sie auf Neues Doc
  3. Geben Sie einen Titel ein und schreiben Sie Ihren Inhalt in Markdown
  4. Fügen Sie Tags zur Organisation hinzu
  5. Klicken Sie auf Speichern

Dokumentation unterstützt vollständige Markdown-Syntax einschließlich:

  • Überschriften und Formatierung
  • Codeblöcke mit Syntaxhervorhebung
  • Tabellen und Listen
  • Bilder und Links

Import von Git

Sie können bestehende Dokumentation aus Ihrem Git-Repository importieren:

  1. Gehen Sie zu Projekteinstellungen > Dokumentationsentdeckung
  2. Konfigurieren Sie Ihre Repository-Verbindung
  3. Klicken Sie auf Docs entdecken
  4. Überprüfen und genehmigen Sie entdeckte Dokumentation

Dies ist perfekt zum Importieren bestehender README-Dateien, technischer Spezifikationen oder Wiki-Inhalte.

Verknüpfung mit Architekturelementen

Dokumentation wird mächtiger, wenn sie mit Ihrer Architektur verknüpft ist:

Links erstellen

  1. Öffnen Sie eine Dokumentationsseite
  2. Klicken Sie auf Mit Element verknüpfen
  3. Suchen oder durchsuchen Sie das Architekturelement
  4. Wählen Sie das/die zu verknüpfende(n) Element(e)
  5. Klicken Sie auf Fertig

Verknüpfte Dokumentation anzeigen

Beim Anzeigen eines Elements im Diagramm erscheint verknüpfte Dokumentation im Detailbereich. Dies bietet sofortigen Kontext, ohne die Diagrammansicht zu verlassen.

Anwendungsfälle für Verknüpfung

  • API-Dokumentation mit Service-Containern verknüpfen
  • Setup-Anleitungen mit Infrastrukturkomponenten verknüpfen
  • Design-Spezifikationen mit Systemkontexten verknüpfen
  • Code-Kommentare mit Code-Elementen verknüpfen

Architecture Decision Records (ADRs)

ADRs dokumentieren wichtige Architekturentscheidungen mit ihrem Kontext und ihren Konsequenzen.

Was ist ein ADR?

Ein Architecture Decision Record erfasst:

Feld Beschreibung
Titel Was entschieden wurde
Status Vorgeschlagen, Akzeptiert, Veraltet, oder Ersetzt
Kontext Warum diese Entscheidung nötig war
Entscheidung Was entschieden wurde
Konsequenzen Auswirkungen der Entscheidung

Einen ADR erstellen

  1. Gehen Sie zum Entscheidungen-Tab in Ihrem Projekt
  2. Klicken Sie auf Neuer ADR
  3. Füllen Sie die ADR-Felder aus
  4. Verknüpfen Sie mit relevanten Architekturelementen
  5. Klicken Sie auf Speichern

ADR-Workflow

ADRs folgen einem Lebenszyklus:

  1. Vorgeschlagen: Erster Entwurf, in Diskussion
  2. Akzeptiert: Entscheidung wurde getroffen und genehmigt
  3. Veraltet: Nicht mehr relevant, aber für Historie behalten
  4. Ersetzt: Durch eine neuere Entscheidung ersetzt

ADR-Entdeckung

Wie Dokumentation können ADRs aus Ihrem Repository entdeckt werden:

  1. Gehen Sie zu Projekteinstellungen > ADR-Entdeckung
  2. Konfigurieren Sie den Pfad zu Ihren ADRs (z.B. docs/adr/)
  3. Klicken Sie auf ADRs entdecken
  4. Überprüfen und genehmigen Sie entdeckte Einträge

Best Practices

Dokumentation aktuell halten

  • Aktualisieren Sie Docs, wenn sich die Architektur ändert
  • Überprüfen Sie Dokumentation während Sprint-Retrospektiven
  • Verwenden Sie ADRs für bedeutende Entscheidungen

Alles verknüpfen

  • Jedes System sollte ein Beschreibungs-Doc haben
  • Verknüpfen Sie ADRs mit betroffenen Komponenten
  • Erstellen Sie Querverweise zu verwandter Dokumentation

Tags effektiv nutzen

  • Taggen nach Domäne (auth, payments, etc.)
  • Taggen nach Typ (api, guide, spec)
  • Taggen nach Status (entwurf, review, final)

ADR-Richtlinien

  • Erstellen Sie ADRs für bedeutende Entscheidungen
  • Fügen Sie betrachtete Alternativen hinzu
  • Dokumentieren Sie die Abwägungen
  • Verknüpfen Sie mit Implementierungs-PRs wenn möglich

Dokumentationsentdeckungs-Einstellungen

Konfigurieren Sie, wie Dokumentation entdeckt wird:

Pfadmuster

Geben Sie an, welche Pfade gescannt werden sollen:

docs/
wiki/
README.md
*.md

Ausschlussmuster

Überspringen Sie bestimmte Dateien:

node_modules/
vendor/
CHANGELOG.md

Nächste Schritte