Workflow: Documentation¶
Dokumentation erstellen, aktualisieren und zusammenfassen.
Übersicht¶
| Aspekt | Details |
|---|---|
| Ziel | Brauchbare Doku aus Code, Configs, Wissen |
| Features | Sub-Agents, Compaction, Templates |
| Formate | Markdown, Confluence, README, Runbooks |
| Output | Strukturierte, konsistente Dokumentation |
Feature-Kombination¶
┌─────────────────────────────────────────────────────────┐
│ QUELLEN │
│ Code, Configs, Notizen, Vendor-Docs │
└───────────────────────────┬─────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│Sub-Agent │ │Sub-Agent │ │Sub-Agent │
│Code-Doku │ │Config- │ │API-Doku │
│ (Haiku) │ │Referenz │ │ (Haiku) │
│ │ │ (Haiku) │ │ │
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
└───────────────┼───────────────┘
▼
┌──────────────────┐
│ Konsolidierung │
│ + Formatierung │
└──────────────────┘
Workflow: README generieren¶
Schritt 1: Projekt analysieren lassen¶
Analysiere dieses Projekt und erstelle ein README:
@./
Inhalt:
- Was macht das Projekt
- Installation
- Konfiguration
- Usage Examples
- Lizenz (falls vorhanden)
Schritt 2: Review und Anpassung¶
Das README ist gut, aber:
- Füge Badges hinzu (Build, Version)
- Erweitere die Examples
- Füge Troubleshooting-Sektion hinzu
Workflow: Runbook erstellen¶
Für Operations-Teams - was tun wenn X passiert.
Schritt 1: Scope definieren¶
Erstelle ein Runbook für unsere FortiGate HA-Umgebung:
Szenarien:
1. Primary Failover
2. Secondary ausgefallen
3. Split-Brain Situation
4. Firmware Upgrade (rolling)
Format: Markdown mit Checklisten
Zielgruppe: 2nd Level Support
Schritt 2: Strukturiertes Runbook¶
Output:
# FortiGate HA Runbook
## Übersicht
| Cluster | Primary | Secondary | VIP |
|---------|---------|-----------|----------|
| fw-prod | fw-01 | fw-02 | 10.0.0.1 |
## Szenario 1: Primary Failover
### Symptome
- [ ] Secondary zeigt "Standalone" oder "Primary"
- [ ] Alerts von Monitoring
- [ ] Traffic läuft über Secondary
### Diagnose
```bash
# Auf Secondary (jetzt Primary)
get system ha status
diagnose sys ha checksum cluster
Maßnahmen¶
- [ ] Ursache auf altem Primary prüfen
- [ ] Wenn Hardware-Fehler: Ticket eröffnen
- [ ] Wenn Software: Logs sichern, Reboot versuchen
- [ ] Nach Recovery: Sync-Status prüfen
Rollback¶
- [ ] Manueller Failback nur im Wartungsfenster
- [ ]
diagnose sys ha reset-uptimeFasse diese FortiOS Admin Guide Sektion zusammen: @docs/fortigate-admin-guide-chapter7.pdf
Fokus: - VPN IPsec Konfiguration - Nur CLI-Befehle (kein GUI) - Häufige Fehler und Lösungen
Output: Markdown Quick-Reference
Das Dokument ist sehr groß. Arbeite es Kapitel für Kapitel durch. Nach jedem Kapitel: /compactAm Ende: Konsolidierte Quick-Reference
Füge Docstrings zu allen Funktionen in @src/api/ hinzu:Format: Google Style Inhalt: Description, Args, Returns, Raises, Example
Erstelle API-Dokumentation für @src/api/routes/:Format: OpenAPI 3.0 YAML Enthält: Endpoints, Parameters, Responses, Examples
## Doku-Skill erstellen
Für konsistente Dokumentation:
```yaml
# ~/.claude/skills/documentation/SKILL.md
---
name: docs
description: Erstellt und aktualisiert Dokumentation.
Aktiviert bei "dokumentiere", "README", "Runbook", "docs".
---
# Documentation Generator
## Formate
### README.md
- Projekt-Titel + kurze Beschreibung
- Badges (optional)
- Installation
- Quick Start
- Configuration
- Examples
- Contributing
- License
### Runbook
- Übersicht (Systeme, Kontakte)
- Szenarien mit Symptomen
- Diagnose-Befehle
- Maßnahmen als Checklisten
- Rollback-Prozeduren
### API Docs
- OpenAPI 3.0 Format
- Alle Endpoints
- Request/Response Examples
- Error Codes
## Stil
- Klar und direkt
- Befehle immer in Code-Blocks
- Checklisten für Prozeduren
- Keine Marketing-Sprache
Tipps für gute Ergebnisse¶
DO ✅¶
Dokumentiere das Ansible-Projekt in @ansible/:
Zielgruppe: Neue Team-Mitglieder
Vorwissen: Linux Basics, kein Ansible
Struktur:
1. Was macht das Projekt
2. Wie ist es aufgebaut (Verzeichnisstruktur)
3. Wie führt man es aus (Step-by-Step)
4. Wie erweitert man es (neue Rolle hinzufügen)
5. Troubleshooting (häufige Fehler)
Zielgruppe, Vorwissen und gewünschte Struktur.
DON'T ❌¶
Welches Format? Welche Tiefe? Für wen?
TIPP: Template verwenden 💡¶
Nutze dieses README-Template für alle meine Projekte:
@templates/README-template.md
Fülle es aus für @projects/new-project/
TIPP: Diff-Dokumentation 💡¶
Nur Änderungen dokumentieren:
Was hat sich zwischen v1.0 und v2.0 geändert?
@releases/v1.0/
@releases/v2.0/
Erstelle ein CHANGELOG.md für v2.0
Kosten-Optimierung¶
| Szenario | Empfehlung |
|---|---|
| Einzelnes README | Sonnet direkt |
| Großes Projekt dokumentieren | Sub-Agents (Haiku) pro Bereich |
| Vendor-Doku zusammenfassen | Sonnet + Compaction |
| Code-Kommentare | Haiku reicht |
Compaction bei großen Docs¶
Dokument: 200 Seiten PDF
Vorgehen:
1. Kapitel 1-5 lesen → Zusammenfassung → /compact
2. Kapitel 6-10 lesen → Zusammenfassung → /compact
3. Finale Konsolidierung
Ohne Compaction: Context-Overflow
Mit Compaction: Funktioniert
Output-Formate¶
Markdown (Default)¶
Confluence Wiki¶
AsciiDoc¶
Troubleshooting¶
Doku ist zu oberflächlich¶
Die Doku ist zu high-level. Erweitere mit:
- Konkreten Konfigurationsbeispielen
- Tatsächlichen Befehlen (nicht Pseudocode)
- Edge Cases und Fehlerbehandlung
Inkonsistenter Stil¶
Die generierten Docs haben unterschiedliche Stile.
Hier unser Style Guide: @docs/style-guide.md
Überarbeite @docs/new-feature.md nach diesem Guide.
Veraltete Doku aktualisieren¶
Diese Doku ist veraltet:
@docs/setup.md
Aktueller Code:
@src/
Aktualisiere die Doku basierend auf dem aktuellen Code.
Markiere Änderungen mit [UPDATED].
Best Practices¶
Zielgruppe zuerst definieren¶
Die wichtigste Variable: Für wen schreibst du?
| Zielgruppe | Stil | Tiefe | Beispiele |
|---|---|---|---|
| Selbst (Referenz) | Knapp, technisch | Maximale Tiefe | Commands, Config-Snippets |
| Kollegen (2nd Level) | Direkt, erklärend | Prozeduren | Schritt-für-Schritt |
| Kunden | Nicht-technisch | Oberfläche | Screenshots, Klickpfade |
| Neue Teammitglieder | Tutoriell | Von Anfang | Vollständige Workflows |
Erstelle Runbook für Szenario X.
Zielgruppe: 2nd Level Support, Linux-Grundkenntnisse vorhanden,
kein Ansible-Wissen.
Schreibstil: Direkte Anweisungen, keine Erklärungen warum.
Living Documentation Ansatz¶
Doku die nicht gepflegt wird ist schlimmer als keine Doku (irreführt):
# Am Ende jeder Doku: Metadaten
---
Letzte Aktualisierung: 2026-03-30
Geprüft gegen: FortiOS 7.4.3
Nächste Review: Quartal 2026-Q2
Owner: Andreas
Claude als Update-Assistent:
Vergleiche diese Doku (@docs/fortigate-setup.md)
mit dem aktuellen Stand (@configs/fw-template.conf).
Markiere veraltete Abschnitte und schlage Updates vor.
Informationsdichte steuern¶
Runbooks zu lang = werden nicht gelesen:
Erstelle das Runbook so:
- Jede Prozedur: Max 10 Schritte
- Bei mehr als 10: In Sub-Prozeduren aufteilen
- Jeder Schritt: Aktion + erwartetes Ergebnis
- Diagnose-Befehle: Immer mit erwartetem Output-Beispiel
Format: Checklisten, keine Fließtext-Blöcke
Diff-basierte Doku-Updates¶
Für regelmäßige Updates effizient:
git diff HEAD~10 -- ansible/ | claude "
Beschreibe diese Ansible-Änderungen für das Ops-Team.
Erstelle einen Changelog-Eintrag für die Doku.
Technisches Level: Jemand der die Playbooks kennt aber
nicht geschrieben hat."
Code-Doku: Was, nicht Wie¶
# SCHLECHTER Docstring (beschreibt das Offensichtliche)
def get_config(host: str) -> str:
"""Holt die Konfiguration vom Host."""
# GUTER Docstring (erklärt das Nicht-Offensichtliche)
def get_config(host: str) -> str:
"""
Holt FortiGate Full-Config via REST API.
Nutzt /api/v2/monitor/system/config/backup mit scope=global.
SSL-Verify ist deaktiviert für Self-Signed Certs in Lab-Umgebungen.
Bei Auth-Fehler (401): Token in Vault prüfen.
Returns:
Vollständige Konfiguration als String (FortiOS Config-Format)
Raises:
ConnectionError: Host nicht erreichbar
PermissionError: API Token ohne read-config Berechtigung
"""
Claude-Prompt: