Projektstruktur
Die Landing-App enthaelt Navigation, Marketingseiten und die eigenen Dokumentationsrouten.
Die API-Dokumentation liest die lokale OpenAPI-Datei und rendert Endpunkte mit JSON-Beispielen fuer Request und Response.
- Gemeinsame UI bleibt in `src/app/componets`.
- Routenbezogene Seiten liegen unter `src/app/...`.
- Die API-Spezifikation ist die Quelle fuer alle Backend-Details.
Lokale Entwicklung
Starten Sie die Next.js-App lokal und pruefen Sie die Doku-Routen vor der Auslieferung.
Testen Sie Benutzer-, Entwickler- und API-Dokumentation getrennt, damit fehlerhafte Verlinkungen schnell auffallen.
- Pruefen Sie `/userdoc/user-guide`, `/developerdoc/builder` und `/api-docs/index.html`.
- Stellen Sie sicher, dass die Locale-Routen unter `/en` und `/de-DE` denselben Inhaltsbereich zeigen.
- Vermeiden Sie clientseitige Zufallswerte in servergerenderten Seiten.
Build und Release
Die Dokumentation wird als normale Next.js-Seite gerendert, daher erfolgt das Deployment wie bei der restlichen Website.
Wenn sich die API aendert, aktualisieren Sie zuerst die OpenAPI-Quelle und pruefen dann die JSON-Beispiele.
- Nutzen Sie einen Production-Build, um Routing- und Metadatenfehler zu finden.
- Kontrollieren Sie nach API-Aenderungen weiterhin Request- und Response-JSON.
- Entfernen Sie alte Pfade, statt sie auf eine andere Doku-Familie umzuleiten.
Inhaltsregeln
Benutzerdokumentation bleibt produktnah, Entwicklerdokumentation bleibt integrationsnah.
Wenn Beispiele noetig sind, verwenden Sie kurze Snippets und JSON-Beispiele, die zum Live-Schema passen.
- Benutzerhandbuch: Workflows, Berechtigungen und Kontoeinrichtung.
- Entwicklerhandbuch: APIs, Routen und Integrationshinweise.
- API-Doku: Payloads auf Endpunkt-Ebene.