Personas and priority tiers

Merlon Docs splits, compiles, and validates sharded Markdown for repos where LLMs help write docs, humans review them, and compiled output serves feature work and end-user guides.

Audience priority

Public pages speak first to the people who can make documentation a required policy.

• Primary: people with authority over reliability. Platform and DevOps leads, engineering and technical managers, QA and reliability engineers, and the person responsible for the team’s AI skill stack. They can require the skill and the check across repositories. The landing page lists these roles and gives them a short path to policy.
• Secondary: people who already value docs. Technical writers and engineers who write things down adopt the skill for themselves and argue for it inside their teams.
• Anti-persona: the engineer who keeps the system in their head. This engineer doesn’t see a problem with undocumented knowledge, even though that knowledge leaves when they do. Public copy addresses the risk this creates for the primary audience instead of arguing with this reader. It stays respectful, because winning them over later is still the goal.

Adoption archetypes

Each archetype is a goal. Interns and students map to Learner, technical writers and domain SMEs to Author, and foundation reviewers to Champion. The landing page names the primary audience’s roles. Archetype tables and WIIFM lines stay goal-based. This rule is advisory: whoever writes or reviews landing copy applies it, and the landing copy’s diff is its evidence. Each archetype gets one WIIFM line (landing-safe):

Archetype	Goal	WIIFM (landing-safe)	Typical path
Builder	Integrate Merlon Docs into repo scripts and CI	One gate for humans, agents, and CI; when each change touches one shard, a doc PR touches fewer files	Paste prompt or run the bootstrap
Learner	Try Merlon Docs before mastering every CLI flag	Paste a prompt; agent runs setup	Getting started prompt
Author	Own content, not the toolchain	One topic per file; load the section that matches the task	Paste prompt + usage model
Champion	Evaluate or sponsor adoption	Judge fit from the vision and the evidence before setup	Vision and claims shards

Paths: CLI README, getting-started workflow, usage model, vision, claims policy.

Once a pipeline exists, adoption archetypes map to tool operator personas below (for example Author → LLM doc author; Builder → wires CI check).

Archetype signals (non-landing)

The signals below help spot each archetype. A job title they name stays off landing pages unless Audience priority above lists it:

• Champion: a CPTO/CTO or platform lead who assesses whether Merlon Docs’ shard contract fits agentic delivery governance, and who reads the vision and claims shards before CLI setup.
• Builder: wires merlon check into CI after Champion sign-off.
• Author / Learner: the roles mapped to them above, such as a technical writer or a student.

Maintainers dogfooding the Merlon Docs monorepo are not an adoption archetype — see This repository and DEVELOPERS.md.

Messaging guardrails

Public copy, landing pages included, follows the claim tiers in Benefit claims and evidence.

Publish landing style

Reference: docs/repo-readme/ → README.md.

• What this tool is (one-liner + vision link for evaluators), then WIIFM; four archetypes max
• WIIFM table does not replace the vision shard for Champions
• Dual equal get-started paths (A/B); Champion eval path in get-started; routing explains fit, not priority
• Want to know more = archetype link hub; keep landing scannable — Mermaid only in the short Merlon Docs 101 section (not elsewhere on the landing)

This style is advisory (Enforceable rules): no check reads the order of docs/repo-readme/ or its WIIFM lines. Whoever edits docs/repo-readme/ applies it, and the README diff is its evidence.

The evidence behind the vision link and the Champion eval path is in Field report: a first external evaluator.

Tool operator personas

Persona	Job	Command
LLM doc author	Edit shards, insert cross-links	shard, compile, check (broken # links)
LLM feature agent	Read doc context while coding	Host search → one shard read
Human doc reviewer	PR quality gate	check, review, prose, lint, links
End-user reader	Read glossary, guides, reviews	compile output

Priority tiers

Capabilities are ranked in three tiers, most important first:

1. An agent can read the docs and write correct links. This tier covers compile, the refs registry, and the check gate.
2. An agent can write docs in shards safely. This tier covers manifest link order, shard split, and the orphan check.
3. A human reviewer can trust the output. This tier covers peer linters and compile hooks.

Below the tiers are the enablers: merlon.config.json wires all commands, and the optional @merlon-docs/merlon-docs-presets package holds the starter markdownlint configs and the Merlon Docs Vale style. Commands for each capability are in the Feature catalog.