​

docs — Public Documentation Standards

​

Critical Rules

1. api-reference/openapi.yaml is the single source of truth — update FIRST, then sync to raff-go → raff-cli → terraform-provider-raff
2. Never include admin/internal endpoints or fields — public API only
3. Auth: X-API-Key only — no JWT, no X-Account-ID, no admin keys
4. Verify before publishing — check endpoint actually works, don’t blindly document
5. Direct language — no marketing, no jargon, go straight to value. Short paragraphs (2-3 sentences max)
6. Update changelog — when adding/changing any API endpoint, add dated entry to the product’s changelog page

​

Writing Style

• Direct — “Create a VM” not “Virtual Machine Creation Guide”
• Simple — make complex things simple, but still comprehensive
• Action-oriented — lead with what the user can DO
• No filler — cut “In order to”, “Please note that”, “It is important to”
• Code examples — curl for API, yaml for Terraform, bash for CLI
• Short paragraphs — 2-3 sentences. If longer, break it up.

​

4 Product Pillars

​

Reference (3 sections)

​

Product Page Template

• docs/products/_template.mdx — Overview page
• docs/products/_template-quickstart.mdx — task how-to
• docs/products/_template-concept.mdx — explainer
• docs/products/_template-details.mdx — spec sheet
• docs/products/_template-troubleshooting.mdx — issue list

​

Sidebar rule — nested sub-groups, no products dropdown

​

Overview page (index.mdx)

1. Frontmatter — `title` is the full product name (e.g. "Virtual Machines") so the HTML `<title>` tag is unique site-wide; `sidebarTitle: Overview` keeps the sidebar label short. Same rule applies to every page: `title` must be unique site-wide; use `sidebarTitle` for short sidebar text. (Mintlify uses the same field for `<title>` and `<h1>` and auto-appends " - Raff" — keep titles ≤ ~50 chars and front-load the product name.)
2. Updated date — <sub>Updated MONTH DAY, YEAR</sub>
3. One paragraph — what it is, key specs, who it's for. Direct, no marketing.
4. Hero <Frame> — /images/products/<pillar>/<product>/hero.png; alt text prefixed with "TODO:" until the real screenshot is dropped in.
5. ## Most viewed — 2x2 CardGroup linking to the 4 dashboard tasks users come for.
6. ## Browse — 2x3 CardGroup linking to the 5 sections (Quickstart & guides, Concepts, Details, Troubleshooting) plus API Reference and Changelog.

​

Standard files per product

products/{pillar}/{product}/
├── index.mdx                    # Overview (the per-product hub)
├── quickstart-guides/           # Dashboard task how-tos (one MDX per task)
│   ├── create-...mdx
│   ├── ...
│   └── delete-...mdx
├── concepts/                    # Explainers (what + why, not how-to)
│   └── ...mdx
├── details/                     # Spec sheets (features, limits, pricing, SLA)
│   ├── features-and-limits.mdx
│   └── pricing.mdx
└── troubleshooting.mdx          # Common issues + recovery (single file)
# NO per-product changelog — use global /api-reference/changelog

​

Changelog (single global page at /api-reference/changelog)

• One changelog for everything — not per-product. Grouped by date → product section.
• API version stays same until finalized (currently v1.0.0)
• Each change has a date, not a version bump
• When finalized → freeze, start next version
• This is NOT the app release log (releases/vX.Y.Z.md)
• Every entry has an emoji tag:
  • 🟢 Added — new endpoint or new parameter
  • 🔵 Updated — changed behavior or new param on existing endpoint (say WHICH part changed)
  • 🟡 Deprecated — still works but will be removed (warn users, tell them what to use instead)
  • 🔴 Removed — endpoint or parameter deleted, no longer available
  • 🟣 Fixed — bug fix on existing endpoint
• Group by date → section (product + reference type):
  ### March 15, 2026
  
  **Virtual Machines — API**
  - 🟢 **Added** — **Resize VM disk storage** — `POST /api/v1/vms/{id}/resize-disk`
  - 🔵 **Updated** — **Create VM** now accepts `enable_ipv6` — `POST /api/v1/vms`
  
  **Projects — CLI**
  - 🟢 **Added** — `raff project create` command
  
• Section format: {Product} — {Reference Type} where reference type is: API, CLI, or Terraform

​

API Reference Rules

​

Before Adding an Endpoint

1. Endpoint must actually work in the backend — don’t document unimplemented features
2. Must be public (customer-facing) — no admin-only endpoints
3. If it returns internal fields, strip them first

​

POST Endpoints — Prerequisites

<Note>
Before creating a VM, you need:
- A **template ID** — get from [List Templates](/api-reference/catalog/list-templates)
- A **pricing plan ID** — get from [List VM Pricing](/api-reference/catalog/list-vm-pricing)
- A **project ID** — get from [List Projects](/api-reference/projects/list-projects)
</Note>

​

Each Endpoint Page

• Method + path
• Description (1-2 sentences)
• Prerequisites (what to fetch first)
• Parameters table (required/optional, type, description, example)
• Request example (curl)
• Response example (actual JSON)
• Error codes specific to this endpoint

​

Mintlify Conventions

• Pages: .mdx format
• Navigation: docs.json
• API endpoints: auto-generated from openapi.yaml
• Components: <Card>, <CardGroup>, <CodeGroup>, <Tabs>, <Accordion>, <Note>, <Warning>
• Icons: use Mintlify icon names (e.g. icon="plus", icon="server")

​

Quick Commands

npx mintlify dev     # Local preview at localhost:3000

​

Sync Order

openapi.yaml (here) → MDX endpoint pages → raff-go → raff-cli → terraform-provider-raff

1. Edit api-reference/openapi.yaml
2. Add/update MDX pages if needed
3. Update product changelog page with dated entry
4. Test locally: npx mintlify dev
5. After merging: sync downstream (raff-go → CLI → Terraform)