Dokumentations-Konventionen

Regeln für alle, die Seiten für diese Dokumentation schreiben — Menschen und Agenten.

Zielgruppe

Kirchenadministratoren, Teamleiter und Volunteers. Keine Entwickler — API-Dokumentation liegt separat in Scalar.

Typisches Nutzerprofil: 30–60 Jahre alt, nicht tech-affin, macht Verwaltung oft ehrenamtlich neben dem Hauptjob. UI und Docs müssen ruhig, klar und offensichtlich sein.

Sprache und Ton

Deutsch (Hochdeutsch, Schweizer Orthographie). ss statt ß. Beispiele: gross, Strasse.
Kurze, direkte Sätze. Imperativ bei Handlungsanweisungen ("Klicke", "Öffne", "Trage ein").
Kein Marketing. Keine Floskeln. Keine Gedankenstriche (em-dash); stattdessen Komma oder Halbgeviertstrich –.
Konsistente Begriffe: siehe Glossar. Insbesondere "Anlass" (nicht "Event"), "Team" (nicht "Gruppe", wenn es um Dienst geht), "Haushalt" (nicht "Familie" in Datenmodell-Kontext).
Währung: CHF mit Hochkomma als Tausendertrenner: 1'000.

Quelle der Wahrheit

Nur shipped und partial Features aus coverage.md dokumentieren.

not started Features bleiben undokumentiert, bis der Code steht.
partial Features bekommen einen <Callout type="warn"> mit dem, was fehlt — Quelle: spec-drift.md.
Wenn Code und FEATURE-LIST.md widersprechen, gilt der Code. Abweichung in spec-drift.md eintragen, nicht kommentarlos angleichen.

Dateistruktur

docs/
  index.mdx                   # Landing Page
  quickstart.mdx              # einseitiger Schnellstart
  glossary.mdx                # einseitiges Glossar
  tutorials/                  # mehrschrittige Lernpfade
  how-to/<modul>/             # Aufgaben-orientierte Rezepte, nach Modul
  reference/<modul>/          # Felder, Optionen, Screens, nach Modul
  concepts/                   # Hintergrund-Artikel
  troubleshooting/            # Symptom → Ursache → Lösung
  changelog/                  # Chronologie (ein MDX pro Release: YYYY-MM-DD.mdx)
  _meta/                      # coverage.md, spec-drift.md, conventions.md

TGDP-Templates

Die Seiten folgen The Good Docs Project:

Quickstart: Overview → Before you start → Teil 1..n → Next steps
Tutorial: Overview → Background → Before you start → Task steps → Summary → Next steps
How-to: Overview → Before you start → Task steps → See also
Reference: Description + tabellarische Struktur (Field | Description | Example)
Concept: Einleitung → (Background) → Use cases → (Comparison) → Related resources
Glossary: Term | Abkürzung | Definition | Quelle Tabelle
Troubleshooting: Pro Symptom: Cause + Solution, mehrfach möglich
Release notes: Neue Features / Improvements / Bug fixes / Known issues pro Release

Fumadocs-Komponenten

Benutze nur, wenn sie einen echten Zweck erfüllen.

<Callout type="info|warn|error"> — Hinweise, Einschränkungen, Warnungen.
<Steps><Step>...</Step></Steps> — alternative nummerierte Schritte (selten nötig; normale 1. Listen reichen meist).
<Tabs> + <Tab value="web">...</Tab> — Platform-Unterschiede (Web vs. Mobile).
<Cards><Card title=... href=... description=... /></Cards> — Section-Landings und "Nächste Schritte".

Frontmatter

Jede MDX-Datei beginnt mit:

---
title: Kurzer Titel
description: Eine Zeile, kein Marker-Talk
icon: IconName # optional, Lucide-Name
---

Screenshots

Alle Screenshots sind Platzhalter: > **TODO Screenshot:** — was zu sehen ist. Keine erfundenen UI-Beschreibungen ausserhalb des Alt-Texts. Keine Fake-Bilder.

Querverweise

Innerhalb der Docs: relative Pfade wie /how-to/people/add-person.
Nie auf externe Marketing-Seiten linken (z. B. iglesio.com) ausser für öffentliche Ressourcen wie Impressum oder Datenschutz.

Git

Jede Änderung in einem Commit mit klarer Botschaft (docs(how-to): add import-people). Nie mehrere unzusammenhängende Module in einem Commit.

Dokumentations-Konventionen

On this page