Strukturierte Dokumentation für Softwareprojekte¶

Ein praxiserprobtes System für Projektdokumentation, das mit dem Code lebt.

Dokumentation ist einer der meistunterschätzten Aspekte der Softwareentwicklung. Ohne klare Struktur veraltet sie schnell, wird inkonsistent oder geht ganz verloren. Dieses System löst das Problem durch eine feste Ordnerstruktur, klare Namenskonventionen und automatisierte Validierung.

Warum strukturierte Dokumentation?¶

In vielen Projekten beginnt Dokumentation als lose Sammlung von Markdown-Dateien im Root-Verzeichnis. Mit der Zeit wachsen diese Dateien unkontrolliert: Doppelte Inhalte, veraltete Informationen und fehlende Verlinkung machen die Dokumentation unbrauchbar.

Das hier beschriebene System wurde über mehrere Projekte hinweg entwickelt und verfeinert. Es basiert auf drei Grundprinzipien:

1. Feste Ordnerstruktur -- Jeder Dokumenttyp hat einen definierten Platz
2. Automatisierte Validierung -- Scripts prüfen Konsistenz und Vollständigkeit
3. Tool-Integration -- Claude Code Rules erzwingen die Einhaltung

Das 4-Ordner-System¶

Die Dokumentation lebt im docs/-Verzeichnis und ist in vier Hauptkategorien unterteilt:

Zusätzlich gibt es optionale Ordner:

• templates/ -- Code-Templates für wiederkehrende Muster (z.B. ERP-Integration)
• examples/ -- Vollständige Integrationsbeispiele
• plans/ -- Temporäre Feature-Pläne (werden nach Abschluss gelöscht)

Diese Trennung sorgt dafür, dass Entwickler schnell die richtige Information finden und Betriebsdokumentation nicht mit internen Entwicklernotizen vermischt wird.

Namenskonventionen¶

Einheitliche Benennung ist entscheidend für die Auffindbarkeit:

Root-Level Dateien wie CODEBASE_KNOWLEDGE.md dienen als Einstiegspunkt und verlinken auf die Detail-Dokumentation in den Unterordnern. Dieses Muster hält die Top-Level-Übersicht kurz und verweist für Details in die Tiefe.

Automatisierte Validierung¶

Ein Shell-Script (check-docs.sh) prüft die Dokumentation auf häufige Probleme:

• Verwaiste Dateien -- Markdown-Dateien, die nirgends verlinkt sind
• Tote Links -- Verweise auf nicht existierende Dateien
• Namenskonventionen -- Dateien, die nicht dem kebab-case-Muster folgen
• Leere Dateien -- Platzhalter, die nie mit Inhalt gefüllt wurden

Das Script lässt sich in die CI/CD-Pipeline integrieren, sodass fehlerhafte Dokumentation den Build blockiert -- genauso wie fehlerhafte Tests.

# Dokumentation validieren
./scripts/check-docs.sh

# Beispiel-Output
[OK] 24 Dateien geprüft
[WARN] docs/development/old-guide.md ist nicht verlinkt
[ERROR] docs/architecture/security.md verweist auf nicht existierende Datei

Claude Code Integration¶

Die stärkste Komponente dieses Systems ist die Integration mit Claude Code. Durch Rules in .claude/rules/ wird sichergestellt, dass die Dokumentationsstruktur bei jeder Änderung eingehalten wird:

• documentation.md -- Definiert die Ordnerstruktur und Naming-Konventionen
• ci-fix.md -- Regelt das Löschen erledigter Pläne und Issues
• verification.md -- Erzwingt die Ausführung von Validierungs-Scripts

Wenn Claude Code ein neues Feature implementiert, erstellt es automatisch die zugehörige Dokumentation im richtigen Ordner, verlinkt sie in der Übersicht und führt die Validierung aus. Die Regel "Kein Feature ohne Doku" wird damit technisch durchgesetzt, nicht nur organisatorisch vereinbart.

Setup für eigene Projekte¶

Das gesamte System ist als Template verfügbar:

1. Template klonen -- aebionix/docs-template als Basis verwenden
2. Ordnerstruktur anlegen -- Die vier Hauptordner erstellen
3. CODEBASE_KNOWLEDGE.md erstellen -- Als zentrale Übersicht
4. Claude Code Rules kopieren -- documentation.md und verification.md in .claude/rules/
5. Validierungs-Script einrichten -- check-docs.sh anpassen und in CI integrieren

Erfahrungen aus dem OPC-Projekt¶

Das OPC-Projekt war das erste, in dem dieses System vollständig eingesetzt wurde. Einige Erkenntnisse:

• Früh starten lohnt sich -- Dokumentation nachträglich zu strukturieren ist um ein Vielfaches aufwändiger als von Anfang an ein System zu haben
• Automatisierung ist Pflicht -- Ohne automatisierte Validierung driftet die Dokumentation innerhalb weniger Wochen ab
• Temporäre Dateien aufräumen -- Der plans/-Ordner muss aktiv gepflegt werden, sonst sammeln sich veraltete Pläne an
• DRY gilt auch für Doku -- Information an genau einer Stelle, Verweise von überall sonst
• Claude Code Rules sparen enorm Zeit -- Statt bei jedem Commit manuell zu prüfen, erzwingt das Tool die Einhaltung automatisch

Das System hat sich in der Praxis bewährt: Die Dokumentation bleibt aktuell, neue Teammitglieder finden sich schnell zurecht, und die Struktur skaliert mit dem Projekt.