Skip to main content

Documentation Workflow with Cursor

Goal: What you change in the code is traceable in cockpit-docs/ — understandable (not just API), including operation (Cron, Env, Webhooks).

Tools:

ToolRole
.cursor/rules/documentation-with-system-changes.mdcMandatory: visible system changes → cockpit-docs/
.cursor/rules/documentation-narrative-and-ops.mdcWhat/Why/Who/Where/Test/Operation + Changelog
project_specs.mdEpics / Milestones (internal)
plattform/changelog.mdShort index of major deliveries
pnpm docs:check (Repo Root)Hint where code is newer than documentation
cockpit-docs/sidebars.ts + NavbarInformation Architecture: one sidebar per role (Editorial, Dashboard, …) — no more mega mainSidebar
Multilingual DocsEN via OpenAI (docusaurus-i18n), Locales de + en

Target Audiences in Documentation​

Mainly: Documentation Target Audiences (Guideline) — Editorial (main users), decision-makers, developers/MCP.

Target AudienceGoalNavbarEntry Point
Content CreatorWork without overwhelmEditorialStart here
GF / Decision-makersWhy, Value, MaturityPlatformDecision-makers & Partners
Developers / MCPArchitecture, APIs, ExtensionsDevelopersStart Development

Primary Target Audience: Editorial (Career Changers)​

Main users: Editors, new employees — not developers.

PrincipleImplementation
Start★ Start here + Short paths (v0, Social, MCP later)
LanguageExplain terms (v0, MCP, Outstand); “you”; no assumed knowledge
OrderChecklist at the top (What/Why/Who/Where/Test), details below; MCP not mixed with v0
Editorial SidebarOnboarding at the top, reference collapsed below
New FeaturesFirst short path in content-creator-handbuch/onboarding-*.md or start-here table, then detail page

Part 1: Cleanly Catch Up (Point 2 — Catch Up Content)​

Not everything at once. Thematically, with the agent in Cursor.

Step A — Inventory (one-time, ~30 Min.)​

In the chat:

Create a documentation gap list: Compare project_specs.md, apps/dashboard/src/config/navigation.ts and the last 20 commits with cockpit-docs/docs/. Output: Table Topic | Code Path | Documentation present? | Priority (high/medium/low).
Do not change code, just list.

Enter the result in project_specs.md under a new heading "Documentation Catch-Up" (or as an issue list).

Step B — One Pass Per Topic​

For each line with priority high (e.g., Social, Releases, Public API, Go-Live):

Documentation catch-up for [TOPIC]. Read the relevant code and existing cockpit-docs pages.
Update or create the appropriate page with: What, Why, Who, Where, How to test, Operation.
Entry in plattform/changelog.md only if it is a larger delivery.
Adjust sidebars. No secrets. Rules: documentation-with-system-changes + documentation-narrative-and-ops.

Order Recommendation: Dashboard user paths → Center website → Developer API → Operation (docs/CRON-SETUP.md + reference).

Step C — Always Check Navigation First​

If navigation.ts or modules.ts changes:

Step D — "Done" Criteria Per Topic​

  • Expert page with mini-template (What … Operation)
  • Changelog entry (if larger delivery)
  • project_specs.md line marked as "implemented" / link set
  • pnpm docs:check without warning for this topic (as far as the script recognizes it)
  • Optional: locally cd cockpit-docs && npm run build

Part 2: Permanently Current (with Cursor)​

It is not possible to be 100% automatic (the agent must understand what is relevant to users). Stable and current can be achieved with a fixed ritual + easy technology.

1. Every Feature Task in Cursor​

At the beginning of the chat (optional, one sentence):

For this task: Provide system changes in cockpit-docs (user + dev), changelog if larger.
Follow rules documentation-with-system-changes and documentation-narrative-and-ops.

The rules are alwaysApply: true — the sentence is still helpful as a focus.

2. Session Closure (before Commit / Push)​

Documentation closure: Check all changes from this session. Is cockpit-docs, changelog, or project_specs missing?
Add now. Short list: which files you touched for documentation.

3. Weekly (5 Min.) or before Release​

pnpm docs:check

In the chat for warnings:

Address the docs:check warnings: update or justify why not necessary for each mentioned documentation page.

Optional: GitHub Action Docs companion check (Mondays) — fails only if the script outputs warnings; you remain responsible for content.

4. Quarterly​

Documentation Audit Q_: Gap list from navigation.ts + project_specs + docs:check. Close top 5 gaps.

5. Docusaurus Version (Technology, not content)​

Every few months: cockpit-docs updated to current 3.x (see docusaurus.io/changelog). Separate from content catch-up.

What Runs Automatically vs. What You Do​

Automatically / Semi-AutomaticallyYou / Cursor Chat
Rules in every session (alwaysApply)Choose topic, initiate catch-up
pnpm docs:check (Git date code vs. documentation)Write texts, explain why
CI Workflow (optional, warning)Maintain changelog + project_specs
Deploy docs.cockpit-os.de after PushSession closure prompt

Short Prompts (Copy & Paste)​

Catch up on a topic: see Step B above.

Only Changelog: Entry in plattform/changelog.md for [FEATURE] from today, with links to detail page.

Only Navigation: navigation.ts has been changed — align navigation-und-module.md and intro references.

Further Reading​

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