diataxis-template

Mein Doku-Skelett für eigene Projekte. Basiert auf Diátaxis von Daniele Procida — vier Quadranten, vier Zwecke, keine Vermischung.

Wozu

Jede meiner Doku-Seiten gehört in genau einen der vier Quadranten. Wenn ich beim Schreiben merke, dass eine Seite in zwei Quadranten passt: aufteilen. Das ist die eine Regel.

Quadrant	Frage	Leser-Modus
Tutorial	Wie lerne ich das?	lernen, an die Hand genommen
How-To	Wie löse ich Problem X?	arbeiten, zielgerichtet
Reference	Was genau ist Y?	nachschlagen, präzise
Explanation	Warum ist das so?	verstehen, einordnen

So benutze ich das Template

1. templates/ in das neue Projekt unter docs/ kopieren.
2. STYLE.md und CONVENTIONS.md mitkopieren (oder per Submodule referenzieren).
3. Pro geplanter Seite: Quadrant zuordnen → entsprechendes Template kopieren → füllen.
4. KI-Anteil pro Quadrant: Reference ~90 %, How-To ~60 %, Tutorial ~30 %, Explanation ~10 %. Reference darf maschinell sein, Explanation nicht.

Reihenfolge beim Aufbau einer Projekt-Doku

1. Reference zuerst — was gibt es? (API, CLI, Config). KI generiert, ich korrigiere.
2. How-Tos — die drei häufigsten Aufgaben. Aus eigenen Päckchen-Specs ableitbar.
3. Ein Tutorial — der eine Pfad vom Nichts zum Erfolgserlebnis. Handarbeit.
4. Explanations — erst wenn das Produkt steht. Warum so, nicht anders.

Nicht andersherum. Tutorials zuerst zu schreiben, bevor klar ist, was das Produkt überhaupt kann, ist die häufigste Falle.

Was hier nicht drinsteht

• Werkzeugkette (mkdocs vs. docusaurus vs. plain Markdown) — projektabhängig.
• Sprache (DE/EN) — projektabhängig.
• Versionierung der Doku — projektabhängig.

Das Template gibt Struktur, nicht Stack.