Documentation Maintenance¶

Quorvex dashboard overview used in documentation visual maintenance.

How to keep Quorvex AI documentation accurate as features, APIs, and dashboard pages change.

Prerequisites¶

• Local checkout of the repository
• Python environment with docs dependencies installed
• Basic familiarity with the feature you changed

pip install -r requirements-docs.txt

Step 1: Choose the Right Page Type¶

Use the Diataxis structure already in docs/:

Do not mix page types. If a page starts becoming both a tutorial and a reference, split the content and link between the pages.

Step 2: Check the Documentation Impact¶

Before opening a PR, check whether your code change affects any of these surfaces:

Step 3: Keep References Source-Aligned¶

Use source files as the authority:

rg -n "^@router\\.(get|post|put|patch|delete)|^@app\\.(get|post|put|patch|delete)|add_api_route" orchestrator/api
rg -n "os\\.getenv|process\\.env|Field\\(.*env" orchestrator web --glob '!node_modules/**'
rg -n "add_argument|click\\.option|typer\\.Option" orchestrator

When updating reference docs, prefer compact tables over prose. Include source file names when the page already uses them.

Run the automated drift check after reference changes. It verifies environment variables, CLI flags, selected public API routes, localhost:8001 API examples, dashboard pages, MkDocs navigation coverage, local documentation image assets, UI visual coverage, and common stale setup strings before running the strict docs build:

make docs-check

Step 4: Keep UI Visuals Current¶

Every published docs page must render at least one UI screenshot or GIF from docs/assets/ui/. Use screenshots for stable pages and short GIFs for multi-step workflows. Do not use terminal screenshots.

When a dashboard workflow changes, update the matching asset entry in docs/assets/ui/visual-assets.manifest.json, start the dashboard, and recapture the UI assets:

BASE_URL=http://localhost:3000 make docs-visual-capture
make docs-visual-check

The capture command writes committed assets under docs/assets/ui/. The check command verifies that each published page has a visible local UI visual with alt text and that manifest assets exist with valid dimensions.

Step 5: Update Navigation¶

If you add a new page, add it to mkdocs.yml under the correct section. Every public docs page should be reachable from the navigation or from a directly related page.

For hidden maintainer notes, use docs/.style-guide.md or another excluded file and document why it is excluded.

Step 6: Build the Docs¶

Run the docs build before submitting:

make docs-check

If MkDocs is not available, install the docs dependencies:

pip install -r requirements-docs.txt
make docs-check

Fix warnings before merging. Broken links, duplicate headings, missing nav entries, invalid Mermaid blocks, missing env vars, missing CLI flags, and stale setup snippets tend to become user-facing gaps quickly.

Step 7: Review for Drift¶

Use this checklist for every docs PR:

• The page has one clear purpose and one audience.
• Commands are copy-pasteable from the repository root unless stated otherwise.
• Links are relative for internal docs.
• API paths, local localhost:8001 curl examples, env vars, dashboard routes, CLI flags, nav entries, and referenced local assets match the code and repository.
• Each published docs page renders a UI screenshot or GIF from docs/assets/ui/.
• Examples avoid real credentials and use placeholders.
• New docs are included in mkdocs.yml.
• make docs-check passes.

Related¶

• Contributing
• Extending the System
• API Endpoints
• Environment Variables
• Web Dashboard