Skip to content
SoundverseSoundverse 2.0 — Engineering Docs

How these docs are structured

These docs are organised by what the reader is trying to do, not by which service a topic belongs to. That principle comes from Diátaxis: separate learning, doing, understanding, and looking-up into distinct kinds of page, and never blend them. The sidebar has seven groups, each one a Diátaxis mode, and a single manifest — scripts/pages.manifest.mjs — declares every page exactly once and drives the whole build.

The seven groups

Section titled “The seven groups”

Every page lives in one of these. The group is the first segment of the page’s slug (get-set-up/quickstart-docker), and it maps to a top-level heading in the left nav.

Group The reader is asking… Diátaxis mode
Start Here “What is this and where do I look first?” Orientation
Get Set Up “Walk me through getting it running.” Tutorial
How-To Guides “How do I make change X?” How-to
Architecture “Why is it built this way?” Explanation
Operations “How do I deploy / debug / operate it live?” How-to (runbook)
Reference “What’s the exact name / signature / value?” Reference
Contributing to Docs “How do I write a good page?” Meta

Five of the seven land squarely on Diátaxis’s four quadrants; Start Here and Contributing to Docs are the onboarding and meta bookends around them.

Diátaxis in one paragraph

Section titled “Diátaxis in one paragraph”

There are four kinds of documentation, and they serve different needs. A tutorial (Get Set Up) is a guided, learning-by-doing path — the reader follows along and it works. A how-to (How-To Guides, Operations) is a recipe for one concrete task the reader already knows they want. An explanation (Architecture) answers “why” — design, trade-offs, the shape of the system. A reference (Reference) is a dry, exhaustive lookup you scan, not read. The one rule that matters: don’t mix modes on a page. A how-to that stops to explain the money path, or a reference table that turns into a tutorial, serves neither reader. If a page wants to do two jobs, split it and cross-link.

Where does my new page go?

Section titled “Where does my new page go?”

Decide by the reader’s intent, in this order:

  1. Are they trying to accomplish one specific task? → a How-To Guide (build/extend a thing) or Operations page (run/deploy/debug something live). Lead with <Steps>; keep the “why” to a one-line aside and link out.

  2. Are they trying to understand how or why the system works? → Architecture. Explanation and a diagram, not a recipe.

  3. Are they looking up an exact fact — a port, an env-var name, an RPC, a route? → Reference. Mostly tables; one row per thing.

  4. Are they brand new and need orientation before any of the above? → Start Here (short, inviting) or a first-run tutorial in Get Set Up.

The manifest is the backbone

Section titled “The manifest is the backbone”

The information architecture is not the filesystem — it’s scripts/pages.manifest.mjs. Every page is declared there once, with its group, slug, title, description, order, optional diagrams, and a brief naming the sources a writer must read and verify. That one file drives:

  • scripts/gen-stubs.mjs — creates a draft stub for any manifest page that doesn’t exist yet, so the sidebar and the build stay green even before a page is written. It never overwrites an existing page — once a page has real content, the writer owns it.
  • The writer fan-out — each page’s brief is what tells a writer agent what to cover and which code: / mem: / GUIDE §NN sources to check against current code.

The left nav itself is generated in astro.config.mjs: each of the seven groups is an autogenerate block pointed at a directory (start-here, get-set-up, how-to, architecture, operations, reference, contributing). Pages self-order within their group by the sidebar.order number in their own frontmatter — ascending, ties broken alphabetically. Flagship guides take order: 1; the Architecture services sub-group deliberately uses order: 20+ so those field-guides trail the top-level architecture pages.

Add a page

Section titled “Add a page”

  1. Add one entry to the manifest. Append a Page object to scripts/pages.manifest.mjs. The slug must be <group-dir>/<page-name>, where <group-dir> is one of the seven autogenerate directories above.

    scripts/pages.manifest.mjs
    {
      group: 'How-To Guides',
      slug: 'how-to/my-new-recipe',
      order: 14,
      title: 'My new recipe',
      description: 'One sentence the sidebar and search will show.',
      brief: 'What to cover + code:/mem:/GUIDE §NN sources to verify against.',
    },

  2. Scaffold the stub. Run node scripts/gen-stubs.mjs. It writes a draft .mdx with your frontmatter and a Draft caution aside; the build is green immediately.

  3. Write the body. Overwrite the stub, keeping the frontmatter title, description, and sidebar.order. Follow the authoring conventions and, for any Mermaid, the diagram guide.

  4. Verify before pushing. npm run verify runs check:secrets, the build, and check:links — the secret scan and internal-link check both gate the pipeline. See running & deploying.

Section titled “Related”