Zum Hauptinhalt springen

Doku-Workflow mit Cursor

Ziel: Was ihr im Code ändert, ist zum Nachlesen in cockpit-docs/ nachvollziehbar — verständlich (nicht nur API), inkl. Betrieb (Cron, Env, Webhooks).

Werkzeuge:

WerkzeugRolle
.cursor/rules/documentation-with-system-changes.mdcPflicht: sichtbare Systemänderungen → cockpit-docs/
.cursor/rules/documentation-narrative-and-ops.mdcWas/Warum/Wer/Wo/Test/Betrieb + Changelog
project_specs.mdEpics / Meilensteine (intern)
plattform/changelog.mdKurzindex großer Lieferungen
pnpm docs:check (Repo-Root)Hinweis, wo Code neuer ist als Doku
cockpit-docs/sidebars.ts + NavbarIA: Sidebar pro Rolle; Navbar nur Redaktion · Plattform · Entwickler + Dropdown Weitere
Mehrsprachige DokuEN per OpenAI (docusaurus-i18n), Locales de + en

Zielgruppen in der Doku​

Maßgeblich: Doku-Zielgruppen (Leitplan) — Redaktion (Hauptnutzer), Entscheider, Entwickler/MCP.

ZielgruppeZielNavbarEinstieg
Content CreatorArbeiten ohne ÜberforderungRedaktionStart hier
GF / EntscheiderWarum, Wert, ReifePlattformEntscheider & Partner
Entwickler / MCPArchitektur, APIs, ErweiterungEntwicklerStart Entwicklung

Primärzielgruppe: Redaktion (Quereinsteiger)​

Hauptnutzer: Redakteurinnen, neue Mitarbeitende — keine Entwicklerinnen.

PrinzipUmsetzung
Start★ Start hier + Kurzpfade (v0, Social, MCP später)
SpracheBegriffe erklären (v0, MCP, Outstand); „du“; kein Annahmen-Wissen
ReihenfolgeOben Checkliste (Was/Warum/Wer/Wo/Test), unten Detail; MCP nicht mit v0 vermischen
Sidebar RedaktionOben Onboarding, unten Referenz eingeklappt
Neue FeaturesZuerst Kurzpfad in content-creator-handbuch/onboarding-*.md oder Start-hier-Tabelle, dann Detailseite

Teil 1: Sauber nachziehen (Punkt 2 — Inhalt aufholen)​

Nicht alles auf einmal. Themenweise, mit dem Agenten in Cursor.

Schritt A — Inventar (einmalig, ~30 Min.)​

Im Chat:

Erstelle eine Doku-Lücken-Liste: Vergleiche project_specs.md, apps/dashboard/src/config/navigation.ts
und die letzten 20 Commits mit cockpit-docs/docs/. Ausgabe: Tabelle Thema | Code-Pfad | Doku vorhanden? | Priorität (hoch/mittel/niedrig).
Kein Code ändern, nur Liste.

Ergebnis in project_specs.md unter neuer Überschrift „Doku-Nachzug“ eintragen (oder als Issue-Liste).

Schritt B — Pro Thema ein Durchlauf​

Pro Zeile mit Priorität hoch (z. B. Social, Freigaben, Public API, Go-Live):

Doku-Nachzug für [THEMA]. Lies den relevanten Code und bestehende cockpit-docs-Seiten.
Aktualisiere oder erstelle die passende Seite mit: Was, Warum, Wer, Wo, So testen, Betrieb.
Eintrag in plattform/changelog.md nur wenn es eine größere Lieferung ist.
Sidebars anpassen. Keine Secrets. Regeln: documentation-with-system-changes + documentation-narrative-and-ops.

Reihenfolge-Empfehlung: Dashboard-Nutzerpfade → Center-Website → Developer-API → Betrieb (docs/CRON-SETUP.md + Verweis).

Schritt C — Navigation immer zuerst abgleichen​

Wenn sich navigation.ts oder modules.ts ändert:

  • Seite navigation-und-module in derselben Aufgabe mitziehen (Regel cockpit-docs-dashboard-navigation.mdc).

Schritt D — „Fertig“-Kriterium pro Thema​

  • Fachseite mit Mini-Vorlage (Was … Betrieb)
  • Changelog-Zeile (wenn größere Lieferung)
  • project_specs.md-Zeile auf „umgesetzt“ / Link gesetzt
  • pnpm docs:check ohne Warnung für dieses Thema (soweit das Skript es erkennt)
  • Optional: lokal cd cockpit-docs && npm run build

Teil 2: Dauerhaft aktuell (mit Cursor)​

100 % automatisch geht nicht (der Agent muss verstehen, was nutzerrelevant ist). Stabil aktuell geht mit festem Ritual + leichter Technik.

1. Jede Feature-Aufgabe in Cursor​

Am Anfang des Chats (optional, ein Satz):

Bei dieser Aufgabe: Systemänderungen in cockpit-docs mitliefern (Nutzer + Dev), Changelog wenn größer.
Regeln documentation-with-system-changes und documentation-narrative-and-ops beachten.

Die Regeln sind alwaysApply: true — der Satz ist trotzdem hilfreich als Fokus.

2. Session-Abschluss (vor Commit / Push)​

Doku-Abschluss: Prüfe alle Änderungen dieser Session. Fehlt cockpit-docs, changelog oder project_specs?
Ergänze jetzt. Kurze Liste: welche Dateien du für Doku angefasst hast.

3. Wöchentlich (5 Min.) oder vor Release​

pnpm docs:check

Im Chat bei Warnungen:

Arbeite die docs:check-Warnungen ab: für jedes Thema die genannte Doku-Seite aktualisieren oder begründen warum nicht nötig.

Optional: GitHub Action Docs companion check (montags) — schlägt nur fehl, wenn das Skript Warnungen ausgibt; ihr bleibt verantwortlich für Inhalt.

4. Quartalsweise​

Doku-Audit Q_: Lücken-Liste aus navigation.ts + project_specs + docs:check. Top 5 Lücken schließen.

5. Docusaurus-Version (Technik, nicht Inhalt)​

Alle paar Monate: cockpit-docs auf aktuelle 3.x (siehe docusaurus.io/changelog). Getrennt vom inhaltlichen Nachzug.

Was automatisch läuft vs. was du tust​

Automatisch / halbautomatischDu / Cursor-Chat
Regeln bei jeder Session (alwaysApply)Thema wählen, Nachzug anstoßen
pnpm docs:check (Git-Datum Code vs. Doku)Texte schreiben, Warum erklären
CI-Workflow (optional, Warnung)changelog + project_specs pflegen
Deploy docs.cockpit-os.de nach PushSession-Abschluss-Prompt

Kurz-Prompts (Copy & Paste)​

Nachzug ein Thema: siehe Schritt B oben.

Nur Changelog: Eintrag in plattform/changelog.md für [FEATURE] von heute, mit Links zur Detailseite.

Nur Navigation: navigation.ts wurde geändert — navigation-und-module.md und intro-Verweise abgleichen.

Weiterführend​

Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /plattform/dokumentation-workflow