CamperCamperDocs
Open app

Get started

Writing docs

Use this page when you add or change articles under apps/docs/content/. The public site is a static export of this tree → getcamper.io/docs.

Audience

Operators — IT / identity admins who configure Camper for a real company. Not application engineers deploying Camper Cloud, and not end users who only need My Access.

Write so a careful admin can complete a task without reading the codebase.

File layout

apps/docs/content/
  index.md                 # docs home
  get-started/…            # signup, quick start, meta
  concepts/…               # how it works, pricing
  directory/…              # SCIM, IdPs, org, SSO
  connections/…            # target apps
  operators/…              # day-to-day product surfaces

Each article is Markdown with YAML frontmatter:

---
title: Short sentence-case title
description: One line for search and previews.
section: Directory          # Get started | Concepts | Directory | Connections | Operators
order: 20                   # sort within section (lower first)
---

URL slug = path under content/ without .md. Trailing slashes are required in links (/directory/scim/).

Article shape (preferred)

  1. Title + short intro — what this page helps you do
  2. Prerequisites (when procedural)
  3. Summary of steps (for multi-step guides)
  4. Numbered procedures with UI paths
  5. Tables for options, roles, and comparisons
  6. What not to do / gotchas only when they prevent real mistakes
  7. Related / Next steps — 3–6 links, not a dump of the whole site

Voice

  • Sentence case titles and headings
  • Short, procedural sentences
  • No emoji in product docs
  • Calm errors: say what failed and what to try next
  • Prefer “you” for the operator; avoid “we recommend” stacks — one clear recommendation is enough

What to omit

Do not put these in product docs:

OmitPut it instead in
Host env vars (GITHUB_APP_*, SLACK_CLIENT_SECRET, …)Internal docs/*-setup.md
Terraform, Cloud Run, Secret Managerdocs/terraform-ci.md, ops runbooks
Database column names, package pathsEngineering docs/domain.md
Issue numbers as the main narrativeOptional at the end of internal docs only
Unpublished roadmap promises as factsMark as direction, or leave out

Operators need what to click and what Camper will do. Host configuration is for Camper operators of the platform, not customers.

Accuracy checklist

Before merging docs for a user-visible feature:

  • Matches current sidebar labels (Catalog, Graph, People, Resources, Connections, Activity, My Access, Settings)
  • Mentions Microsoft 365 where connections are listed (beta is fine)
  • Separates directory (SCIM) from targets (Connections) and sign-in (SSO)
  • Roles use Admin / Viewer (omit); never tell people to SCIM Owner
  • Dry-run / no write-until-confirm is stated on resource linking pages
  • Cross-links use trailing slashes
  • Preview: pnpm --filter @camper/docs dev (usually :3002 under /docs/)
  • Build: pnpm --filter @camper/docs build

When a feature ships

Product docs ship in the same PR as user-visible behavior. Internal docs/*.md notes are not a substitute for apps/docs/content/.