How this documentation is organised

The plexsphere docs follow Diátaxis. Diátaxis observes that technical documentation serves four distinct needs, and that a page which tries to serve more than one of them serves none of them well. The four needs are learning, doing, information, and understanding, and they map to four quadrants:

Quadrant	Serves	Reader's question	Voice
Tutorials	learning	"Teach me."	A lesson. Hand-held, guaranteed to work, no choices.
How-to guides	a task	"How do I do X?"	A recipe. Assumes competence, addresses a goal.
Reference	information	"What exactly is X?"	A specification. Dry, accurate, exhaustive.
Explanation	understanding	"Why is it like this?"	A discussion. Trade-offs, history, alternatives.

In this repository the four quadrants live under docs/tutorials/, docs/how-to/, docs/reference/, and the explanation quadrant — which spans docs/architecture/ (the system map) and docs/contexts/ (the bounded-context model). Two further areas sit outside the four quadrants: docs/operations/ collects cross-cutting operational runbooks that span more than one bounded context — how-to in voice, but platform-wide rather than scoped to a single surface — and docs/contributing/ is the practical contributor handbook for working on the repository itself.

The compass — telling the quadrants apart

The two distinctions people get wrong are tutorial-vs-how-to and reference-vs-explanation. The compass resolves both:

• Tutorial vs. how-to. A tutorial serves a learner who does not yet know what to ask; the author chooses the path and guarantees the outcome. A how-to serves a practitioner who already has a goal; it is the shortest correct path to their result, not a lesson. "First hour with plexsphere" is a tutorial; "rotate the signing key" is a how-to.
• Reference vs. explanation. Reference describes the machinery and nothing else — the endpoint's fields, the flag's default, the schema. Explanation never states a bare contract; it argues, weighs alternatives, and gives context. If a reader could disagree with a sentence, it is explanation; if they could only mis-read it, it is reference.

A practical test: write the page's purpose as one sentence. If it contains "learn", it is a tutorial. If it contains "in order to", it is a how-to. If it is a noun phrase ("the /v1/domains surface"), it is reference. If it contains "because" or "rather than", it is explanation.

Placing a new page

1. Decide the single need the page serves and pick its quadrant.
2. Put the file under that quadrant's directory and set quadrant: in the frontmatter to match (the frontmatter gate rejects a mismatch). The one exception is a cross-cutting operational runbook: it is how-to in voice (quadrant: how-to) but lives under docs/operations/ because it spans more than one bounded context rather than addressing a single surface.
3. Add one sidebar entry under the matching group in docs/.vitepress/config.ts — the sidebar drift gate fails until every page is reachable.
4. If the page is drifting toward a second need, split it. A how-to that keeps explaining why wants an explanation page next to it and a link between them; a reference page that starts teaching wants a tutorial.

The full mechanical contract — sentence-case headings, the frontmatter schema, the rule that internal identifiers never reach rendered output — lives in Docs authoring conventions. This page is the why; that one is the how.

Why we adopted it

Before Diátaxis the corpus was organised by subsystem, which meant every page mixed a little teaching, a little procedure, a little specification, and a little rationale — and a reader looking for any one of those had to mine all four out of every page. Splitting by reader need rather than by subsystem makes each page answer exactly one question, which is both easier to write and far easier to read. The trade-off is that one subsystem's story is now spread across four quadrants; the cross-references at the foot of each page exist to stitch it back together for the reader who wants the whole thread.