# Documentation personas (shared across all Norsk ctl product repos)

The shared reader vocabulary. Every Norsk ctl product — probe, commentary,
playout, the turnkeys — writes docs for the same four personas, so a reader who
learns one product's docs knows how to navigate the next. Read this before
writing or restructuring a product's `docs/`; then keep the product's own
`docs/personas.md`, which maps _this_ product's named audiences and runtime
roles onto the four below.

This is a **shipped reference**, not a drift-gated copy: you consume it from
`node_modules/@norskvideo/ctl-dev-kit/conventions/personas.md`, you do not copy
it into the repo. The per-product mapping legitimately differs product to
product, so there is nothing byte-identical to gate — the shared thing is the
vocabulary, not the mapping.

## The four personas

Two extremes (casual / deep-tech) miss the two middle personas that most docs
actually serve. Each persona has a fixed sub-structure — Skills / Wants / Doc
needs / Failure mode — so a product can fill it in the same shape.

### 1. Evaluator

Just heard about the product. A developer, a PM at a broadcaster, a technical
founder — or a **sales engineer demoing it on their behalf**. Wants to know
"does this do what I need?" in 15 minutes.

- **Skills**: variable — assume no Docker / ffmpeg / transport-protocol knowledge.
- **Wants**: a result on screen within a few minutes; clarity on what just
  happened; confidence they won't hit a wall going further. A demo-driver also
  wants it to read as credible and legible live on a shared screen.
- **Doc needs**: one quick start, zero-to-running. Happy path only, no flags. A
  gallery that shows the product's range at a glance.
- **Failure mode**: opens a page with twelve sidebar entries (or a dense form),
  bounces.

### 2. Builder

Building or standing up a real deployment _with_ the product. A developer or a
technical producer/operator. Wants it to work; does not want to become a DevOps
expert, and does not want to hand-write config/graph YAML.

- **Skills**: can run commands, knows what a container is. May be deeply fluent
  in the product's _domain_ (broadcast transports, say) while still not wanting
  ctl/Docker internals — a product refines this in its own mapping.
- **Wants**: task-oriented hand-holding; a UI that exposes everything; good
  errors with fix hints; sensible defaults.
- **Doc needs**: task guides ("how to do X") with screenshots. A troubleshooting
  checklist. Not compose YAML, not env vars, not architecture diagrams.
- **Failure mode**: hits an error, can't tell if it's their fault or a bug,
  gives up.
- **Usually the most underserved persona**, and usually the product's sweet
  spot — the Integrator has generated reference, the Evaluator has zero-to-hero,
  the Administrator is largely ctl's; the Builder's task guides are the product's own
  work and the thing most worth investing in.

### 3. Integrator

Automating against the product or wiring it into a larger system. Scripted
launches, CI/CD, programmatic control.

- **Skills**: comfortable with CLIs, API calls, shell; trusts tools, reads flags.
- **Wants**: reference that matches reality; copy-pastable invocations; scripting
  examples; clear error codes; idempotent operations for CI.
- **Doc needs**: CLI reference (generated), API reference (from OpenAPI), a
  config-file/schema reference, a short recipes page.
- **Failure mode**: the reference has drifted from the tool; trust is lost; they
  read the source instead.

### 4. Administrator (SRE)

Running the product in production. Responsible for uptime, cost, security.

- **Skills**: deep Docker, nginx/networking/TLS; reads source when docs are thin.
- **Wants**: what the platform does to the host — ports bound, files touched,
  where state lives, secrets, crash/restart, backup/restore, upgrade/DR.
- **Doc needs**: an honest architecture doc, a production deployment guide, a
  security reference.
- **Failure mode**: docs are too happy-path, omit failure modes; can't tell if
  the thing is production-ready.

### On decision-makers

CFO / commercial personas are a marketing concern, not a docs one. The useful
middle is a **decision-maker evaluating for their team** — "should we build on
this?" — served by one honest overview page (scale, maintenance, lock-in, CI),
no marketing copy. Don't build a separate doc track for it.

## Ownership: the persona handoff

The persona a page serves decides which repo owns it, once products are split
out of ctl:

| Persona       | Owner repo                                                                                                               |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Evaluator     | **product**                                                                                                              |
| Builder       | **product**                                                                                                              |
| Integrator    | **both** — the product owns its config schema + CLI subtree + API fragment; ctl owns the daemon verbs and the shared API |
| Administrator | **ctl** — host footprint, ports, TLS, upgrade/DR are the platform's story, not any one product's                         |

The test: **if the answer changes when you swap products, it's product docs; if
it changes when you upgrade ctl, it's ctl docs.** Ownership is not presentation —
a single rendered site can still interleave both (see norsk-ctl's
`_planning/docs-after-the-split.md`).

## Runtime actors are not doc-reader personas

A deployed product has **runtime actors** — the roles people play in the running
system (an operator at a console, a guest who joins, an analyst who reads a
report). These are _not_ a fifth, sixth, seventh persona, and indexing docs by
them is the most common way a product's docs sprawl.

Reconcile them like this:

- The actor who **sets the deployment up and runs it** is the **Builder** (and,
  live, the Administrator in the ctl sense) — the same human, wearing hats.
  Their material is the Builder task guides. Neither hat is an **access role**:
  norsk-ctl's platform roles (RFC 0003 §2.6, ADR-0013) say what a signed-in
  principal may _do_, and two of their names collide with persona names —
  Builder/`builder` and Administrator/`admin` — by coincidence, not by design.
  A persona is who you write for; a role is what an enforcement point checks.
  The roles are not listed here: this file ships to every product repo with no
  gate tying it to the ladder, so a copy of the list would rot unnoticed.
- Actors who are **invited into** the running deployment (a guest, a
  contributor) rarely read the manual at all — they receive a link, and maybe an
  onboarding message. Material authored _for_ them but _handed out by_ the
  Builder — join-page guides, onboarding email templates — is **distribution /
  onboarding kit**, indexed separately from the Builder's own task guides, not
  as manual chapters.

Map each product's named audiences (from its `PRODUCT.md`) onto the four
personas above; don't invent a parallel scheme. Keep the per-product mapping in
the product's `docs/personas.md`.

## The journey table

A persona is who you write for; a journey is where they go. Each product's
`docs/personas.md` carries one table, in this shape, and `docs/journeys.ts` in
this package checks it from `bun run docs:check`: every persona has one row,
every page it names exists, no route is longer than five pages, and every route
ends in a hand-off.

| Persona       | Starts at               | Then, in order                                        | Hands off to                                         |
| ------------- | ----------------------- | ----------------------------------------------------- | ---------------------------------------------------- |
| Evaluator     | `/docs/`                | `/docs/quickstart/`, `/docs/guides/gallery/`          | Guides (build with it) or ctl (run it for real)      |
| Builder       | `/docs/guides/first-…/` | the task pages, `/docs/guides/troubleshooting/`       | Reference, for the settings they just used           |
| Integrator    | `/docs/reference/`      | config, CLI subtree, API, recipes                     | norsk-ctl's CLI and API reference                    |
| Administrator | `/docs/how-to/`         | what this product adds to the host, known limitations | norsk-ctl's manual, for everything about the machine |

The Integrator's route may start at a recorded API walkthrough (the `-api`
variant of the Builder's first task) rather than at Reference; the Manager's
"API tokens, HTTP API" is the pattern. Reference stays where it ends.

Site paths are `/docs/...` (the embedded base; the public build strips it) and
resolve to `website/src/content/docs`; a bare `name.md` resolves under `docs/`.
The hand-off is where "see norsk-ctl for details" lives, once per route, so no
page needs the caveat sprinkled through it. A repo with no site and no
`docs/quickstart.md` (a backend-only turnkey) is not asked for the table.