Qualität und Prozess

Diese Seite gilt für alle Inhalte unter apps/docs. Sie richtet sich an Menschen und Agenten, die Produktverhalten beschreiben. Ziel ist aktuelle, prüfbare Dokumentation ohne Secrets und ohne vermischte Zielgruppen.

Prinzipien

• Dokumentiert wird der ausgelieferte Stand, nicht die Roadmap als Fakt.
• Geplante Funktionen heißen geplant oder Roadmap, Beta-Funktionen Beta.
• UI-Begriffe entsprechen der deutschen Oberfläche.
• Widget-API und öffentliche REST-API bleiben getrennte Bereiche.
• Keine echten API-Keys, Signing-Secrets, Tokens, Passwörter oder personenbezogenen Testdaten.

Definition of Done

Eine dokumentationsrelevante Änderung ist erst fertig, wenn alle Punkte zutreffen:

1. Same-PR-Docs. Die Seitenänderung liegt im selben Pull Request wie die Produkt-, API- oder Betriebsänderung. Nachträgliche Docs-only-PRs ersetzen das nicht, außer bei reiner Rechtschreibung ohne Verhaltenswechsel.
2. Kein Secret. Keine Klartext-Keys (orb_api_…, orb_cal_…, whsec_…), keine Produktions-Umgebungsgeheimnisse, keine internen Hashes. Platzhalter sind YOUR_API_KEY und YOUR_CALENDAR_TOKEN.
3. check-docs.mjs. Der Docs-Build führt node ./scripts/check-docs.mjs aus. Der Check muss in npx turbo run build --filter=docs grün sein.
4. E2E docs-portal. Die Suite apps/e2e/tests/docs-portal.spec.ts deckt die von außen sichtbare Produktreise des Dokumentationsportals ab (Startseite, Navigation, Suche, zentrale Bereiche). Ein Feature am Portal darf nicht als fertig gelten, solange dieser Test fehlt oder fehlschlägt.

Zusätzlich für die REST-API: OpenAPI zuerst, Changelog vor Breaking Changes, apps/e2e/tests/integrations.spec.ts analog zum Dokumentationsstandard.

Ablauf

1. Betroffene Produktreise und Zielgruppe benennen.
2. Bestehende Seite erweitern oder aus Vorlage Anleitung beziehungsweise Vorlage Referenz anlegen.
3. Sidebar in apps/docs/astro.config.mjs nur ändern, wenn ein neuer Slug entsteht.
4. Lokal npx turbo run build --filter=docs ausführen.
5. Den relevanten E2E-Lauf starten: docs-portal für Portaländerungen, integrations.spec.ts für den öffentlichen REST-Vertrag.
6. Im Pull Request die geprüften Befehle nennen. Keine Secrets in Logs oder Screenshots.

Sprache und Struktur

Vorlagen erzwingen eine gemeinsame Gliederung. Anleitungen beschreiben Aufgaben („Kurs anlegen“), Referenzen beschreiben Verträge (Felder, Fehler, Limits). Mischseiten vermeiden: erst die Aufgabe, Verweis auf die Referenz.

Schreibregeln stehen in Schreibstil. Status von Fähigkeiten nicht frei erfinden; sie folgen dem ausgelieferten Code und docs/product/capability-status.json.

Betrieb

Wie das Portal lokal läuft und wie die geplante Veröffentlichung gedacht ist, steht in Dokumentationsportal betreiben. Die produktive Domain darf erst als erreichbar beschrieben werden, wenn der Betrieb das ausdrücklich bestätigt.