@norskvideo/ctl-dev-kit 0.1.15 → 0.1.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/conventions/CLAUDE.core.md +11 -0
- package/conventions/personas.md +127 -0
- package/package.json +1 -1
|
@@ -65,5 +65,16 @@
|
|
|
65
65
|
(`norsk-ctl-product-playout`, `-commentary`) or beside the code they guard
|
|
66
66
|
(`-probe`, `-turnkey-funke-pegasus`) is the repo's choice — the contract is
|
|
67
67
|
the IDs and the guard, not the layout.
|
|
68
|
+
- **Know who reads it — name the persona before writing docs or a
|
|
69
|
+
persona-facing surface.** Every Norsk ctl product writes for the same four
|
|
70
|
+
reader personas — Evaluator, Builder, Integrator, Operator (SRE) — defined in
|
|
71
|
+
`@norskvideo/ctl-dev-kit/conventions/personas.md`, with this product's own
|
|
72
|
+
audiences mapped onto them in its `docs/personas.md`. Before writing or
|
|
73
|
+
restructuring docs, a configure/dashboard surface, onboarding material, or any
|
|
74
|
+
copy a persona will read, name that reader and honour the ownership handoff
|
|
75
|
+
(Evaluator/Builder -> product repo, Operator -> ctl, Integrator -> both).
|
|
76
|
+
Runtime actors (the roles people play in the deployed product) are NOT
|
|
77
|
+
doc-reader personas: the operator who runs it is the Builder; guests who are
|
|
78
|
+
invited in receive onboarding kit, they don't read the manual.
|
|
68
79
|
|
|
69
80
|
<!-- END ctl-shared-conventions v1 -->
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
# Documentation personas (shared across all Norsk ctl product repos)
|
|
2
|
+
|
|
3
|
+
The shared reader vocabulary. Every Norsk ctl product — probe, commentary,
|
|
4
|
+
playout, the turnkeys — writes docs for the same four personas, so a reader who
|
|
5
|
+
learns one product's docs knows how to navigate the next. Read this before
|
|
6
|
+
writing or restructuring a product's `docs/`; then keep the product's own
|
|
7
|
+
`docs/personas.md`, which maps *this* product's named audiences and runtime
|
|
8
|
+
roles onto the four below.
|
|
9
|
+
|
|
10
|
+
This is a **shipped reference**, not a drift-gated copy: you consume it from
|
|
11
|
+
`node_modules/@norskvideo/ctl-dev-kit/conventions/personas.md`, you do not copy
|
|
12
|
+
it into the repo. The per-product mapping legitimately differs product to
|
|
13
|
+
product, so there is nothing byte-identical to gate — the shared thing is the
|
|
14
|
+
vocabulary, not the mapping.
|
|
15
|
+
|
|
16
|
+
## The four personas
|
|
17
|
+
|
|
18
|
+
Two extremes (casual / deep-tech) miss the two middle personas that most docs
|
|
19
|
+
actually serve. Each persona has a fixed sub-structure — Skills / Wants / Doc
|
|
20
|
+
needs / Failure mode — so a product can fill it in the same shape.
|
|
21
|
+
|
|
22
|
+
### 1. Evaluator
|
|
23
|
+
|
|
24
|
+
Just heard about the product. A developer, a PM at a broadcaster, a technical
|
|
25
|
+
founder — or a **sales engineer demoing it on their behalf**. Wants to know
|
|
26
|
+
"does this do what I need?" in 15 minutes.
|
|
27
|
+
|
|
28
|
+
- **Skills**: variable — assume no Docker / ffmpeg / transport-protocol knowledge.
|
|
29
|
+
- **Wants**: a result on screen within a few minutes; clarity on what just
|
|
30
|
+
happened; confidence they won't hit a wall going further. A demo-driver also
|
|
31
|
+
wants it to read as credible and legible live on a shared screen.
|
|
32
|
+
- **Doc needs**: one quick start, zero-to-running. Happy path only, no flags. A
|
|
33
|
+
gallery that shows the product's range at a glance.
|
|
34
|
+
- **Failure mode**: opens a page with twelve sidebar entries (or a dense form),
|
|
35
|
+
bounces.
|
|
36
|
+
|
|
37
|
+
### 2. Builder
|
|
38
|
+
|
|
39
|
+
Building or standing up a real deployment *with* the product. A developer or a
|
|
40
|
+
technical producer/operator. Wants it to work; does not want to become a DevOps
|
|
41
|
+
expert, and does not want to hand-write config/graph YAML.
|
|
42
|
+
|
|
43
|
+
- **Skills**: can run commands, knows what a container is. May be deeply fluent
|
|
44
|
+
in the product's *domain* (broadcast transports, say) while still not wanting
|
|
45
|
+
ctl/Docker internals — a product refines this in its own mapping.
|
|
46
|
+
- **Wants**: task-oriented hand-holding; a UI that exposes everything; good
|
|
47
|
+
errors with fix hints; sensible defaults.
|
|
48
|
+
- **Doc needs**: task guides ("how to do X") with screenshots. A troubleshooting
|
|
49
|
+
checklist. Not compose YAML, not env vars, not architecture diagrams.
|
|
50
|
+
- **Failure mode**: hits an error, can't tell if it's their fault or a bug,
|
|
51
|
+
gives up.
|
|
52
|
+
- **Usually the most underserved persona**, and usually the product's sweet
|
|
53
|
+
spot — the Integrator has generated reference, the Evaluator has zero-to-hero,
|
|
54
|
+
the Operator is largely ctl's; the Builder's task guides are the product's own
|
|
55
|
+
work and the thing most worth investing in.
|
|
56
|
+
|
|
57
|
+
### 3. Integrator
|
|
58
|
+
|
|
59
|
+
Automating against the product or wiring it into a larger system. Scripted
|
|
60
|
+
launches, CI/CD, programmatic control.
|
|
61
|
+
|
|
62
|
+
- **Skills**: comfortable with CLIs, API calls, shell; trusts tools, reads flags.
|
|
63
|
+
- **Wants**: reference that matches reality; copy-pastable invocations; scripting
|
|
64
|
+
examples; clear error codes; idempotent operations for CI.
|
|
65
|
+
- **Doc needs**: CLI reference (generated), API reference (from OpenAPI), a
|
|
66
|
+
config-file/schema reference, a short recipes page.
|
|
67
|
+
- **Failure mode**: the reference has drifted from the tool; trust is lost; they
|
|
68
|
+
read the source instead.
|
|
69
|
+
|
|
70
|
+
### 4. Operator (SRE)
|
|
71
|
+
|
|
72
|
+
Running the product in production. Responsible for uptime, cost, security.
|
|
73
|
+
|
|
74
|
+
- **Skills**: deep Docker, nginx/networking/TLS; reads source when docs are thin.
|
|
75
|
+
- **Wants**: what the platform does to the host — ports bound, files touched,
|
|
76
|
+
where state lives, secrets, crash/restart, backup/restore, upgrade/DR.
|
|
77
|
+
- **Doc needs**: an honest architecture doc, a production deployment guide, a
|
|
78
|
+
security reference.
|
|
79
|
+
- **Failure mode**: docs are too happy-path, omit failure modes; can't tell if
|
|
80
|
+
the thing is production-ready.
|
|
81
|
+
|
|
82
|
+
### On decision-makers
|
|
83
|
+
|
|
84
|
+
CFO / commercial personas are a marketing concern, not a docs one. The useful
|
|
85
|
+
middle is a **decision-maker evaluating for their team** — "should we build on
|
|
86
|
+
this?" — served by one honest overview page (scale, maintenance, lock-in, CI),
|
|
87
|
+
no marketing copy. Don't build a separate doc track for it.
|
|
88
|
+
|
|
89
|
+
## Ownership: the persona handoff
|
|
90
|
+
|
|
91
|
+
The persona a page serves decides which repo owns it, once products are split
|
|
92
|
+
out of ctl:
|
|
93
|
+
|
|
94
|
+
| Persona | Owner repo |
|
|
95
|
+
| ---------- | ------------- |
|
|
96
|
+
| Evaluator | **product** |
|
|
97
|
+
| Builder | **product** |
|
|
98
|
+
| Integrator | **both** — the product owns its config schema + CLI subtree + API fragment; ctl owns the daemon verbs and the shared API |
|
|
99
|
+
| Operator | **ctl** — host footprint, ports, TLS, upgrade/DR are the platform's story, not any one product's |
|
|
100
|
+
|
|
101
|
+
The test: **if the answer changes when you swap products, it's product docs; if
|
|
102
|
+
it changes when you upgrade ctl, it's ctl docs.** Ownership is not presentation —
|
|
103
|
+
a single rendered site can still interleave both (see norsk-ctl's
|
|
104
|
+
`_planning/docs-after-the-split.md`).
|
|
105
|
+
|
|
106
|
+
## Runtime actors are not doc-reader personas
|
|
107
|
+
|
|
108
|
+
A deployed product has **runtime actors** — the roles people play in the running
|
|
109
|
+
system (an operator at a console, a guest who joins, an analyst who reads a
|
|
110
|
+
report). These are *not* a fifth, sixth, seventh persona, and indexing docs by
|
|
111
|
+
them is the most common way a product's docs sprawl.
|
|
112
|
+
|
|
113
|
+
Reconcile them like this:
|
|
114
|
+
|
|
115
|
+
- The actor who **sets the deployment up and runs it** is the **Builder** (and,
|
|
116
|
+
live, the Operator in the ctl sense) — the same human, wearing hats. Their
|
|
117
|
+
material is the Builder task guides.
|
|
118
|
+
- Actors who are **invited into** the running deployment (a guest, a
|
|
119
|
+
contributor) rarely read the manual at all — they receive a link, and maybe an
|
|
120
|
+
onboarding message. Material authored *for* them but *handed out by* the
|
|
121
|
+
Builder — join-page guides, onboarding email templates — is **distribution /
|
|
122
|
+
onboarding kit**, indexed separately from the Builder's own task guides, not
|
|
123
|
+
as manual chapters.
|
|
124
|
+
|
|
125
|
+
Map each product's named audiences (from its `PRODUCT.md`) onto the four
|
|
126
|
+
personas above; don't invent a parallel scheme. Keep the per-product mapping in
|
|
127
|
+
the product's `docs/personas.md`.
|