​

Docs contribution guide

​

Where the page-type patterns live

• Guides (guides/*.mdx) — how-to pages a tenant follows end to end: onboarding walks, first sends, channel setup, console walkthroughs, and the hub orientation maps (see The orientation page pattern). A guide is the class the reader “does something with.”
• Concepts (concepts/*.mdx) — one-page explanations of a model or a capability: what it is, how its pieces fit, where its limits sit. A concept is the class the reader “understands something with.”
• Channels (channels/*.mdx) and Voice (voice/*.mdx) — per-channel/per-surface anchor pages.
• API Reference (api-reference/*.mdx), SDKs (sdks/*.mdx), Reference (reference/*.mdx), Legal (legal/*.mdx) — the contract-facing and legal surface.
• The Getting Started anchor pages (introduction.mdx, quickstart.mdx, authentication.mdx, docs-languages.mdx, this page) — the pages a first reader of the whole site needs before anything else.

​

How to add a page

​

1. Write the page with front matter

---
title: "Page title shown to the reader"
description: "One sentence on what this page answers — used by search and the pin."
---

# The page's H1 repeats the title

​

2. Register the page in docs.json

​

3. Write the source-pin test

/**
 * STRUCTURAL-PIN: <page path> — <what class of page and what it pins>.
 * A docs .mdx cannot be imported, so this pins rendered file structure
 * (the only viable pin for a content surface).
 * DUAL-HARNESS SAFE: register through the vitest global when present,
 * falling back to node:test.
 */
import { readFileSync, existsSync } from "node:fs";
import { test as nodeTest } from "node:test";
import assert from "node:assert/strict";
import { fileURLToPath } from "node:url";
import { dirname, join } from "node:path";

const test = globalThis.test ?? nodeTest;
const HERE = dirname(fileURLToPath(import.meta.url));
const DOC = join(HERE, "..", "<page-file>.mdx");
const NAV = join(HERE, "..", "..", "docs.json");

test("<page> exists with valid frontmatter", () => {
  assert.ok(existsSync(DOC), "<page>.mdx missing");
  const src = readFileSync(DOC, "utf8");
  assert.ok(/^---\ntitle: "/.test(src), "frontmatter must open with a title");
  assert.ok(/description: "/.test(src), "frontmatter must carry a description");
});

test("<page> carries the sections it promises", () => {
  const src = readFileSync(DOC, "utf8");
  for (const marker of ["## <section heading>", "<promised surface>"])
    assert.ok(src.includes(marker), `missing section: ${marker}`);
});

test("<page> is registered in docs.json exactly once", () => {
  const raw = readFileSync(NAV, "utf8");
  let count = 0;
  JSON.stringify(JSON.parse(raw), (_k, v) => {
    if (v === "<page-path-without-extension>") count += 1;
    return v;
  });
  assert.equal(count, 1, "docs.json must reference <page> exactly once");
});

​

The orientation page pattern

1. The one-sentence question that brings the reader in, answered by the whole map (e.g. where do I run a channel?).
2. A tile map — one section per console on the hub, each holding the console’s live route in a code span (/messages/sms), the one-sentence question that console answers, first-visit skip conditions (what to do when the console has no sender / no registration yet), and a Docs: line of links to the in-depth guides behind that console.
3. A closing table that links the in-depth pages the map promised, so the reader’s next click off the hub is already open.

​

The concept model page pattern

1. A one-paragraph capability statement at the top — the single paragraph that says what the capability does for the tenant, in the tenant’s vocabulary (not the internal subsystem’s).
2. A model diagram or an ordered model section — the piece-by-piece walk of how the capability fits together (the audit-ledger model’s “three planes”, the termination model’s travel modes, every lifecycle’s ordered states). Readers remember the model; the rest of the page is there to fill it in.
3. Limits and boundaries — what the capability deliberately does NOT do, where the limits sit, which surfaces move it (consoles, API routes, exports).
4. Cross-links out — a concept page ends by naming the guide(s) that put the model to work and the hub page that maps it.

​

The guide page pattern

1. Who the guide is for and the outcome it produces, in the first paragraph.
2. First-visit skip conditions — the state a tenant in which this guide does not apply (“if you only need plain text, SMS covers it; skip this”) and the prerequisite console state (“until a sender is registered the console routes you to the sender-onboarding flow first”). A guide that names its skip conditions saves the reader a dead walkthrough.
3. Live console paths — every console route the guide touches appears as a literal code span (/messages/whatsapp, /audience/segments), and the guide matches the live route 1:1 (the pin asserts these routes).
4. Docs links — the in-depth concept page(s) the guide leans on, in a closing “Docs:” line, so the guide never re-teaches the concept.

​

When to choose each pattern

• If you are mapping a single dashboard hub with more than about eight consoles, write one orientation page under guides/, with a tile-map pin.
• If the reader’s question is “how does X actually work” (a model, a lifecycle, a capability with pieces), write a concept page under concepts/ (capability paragraph → model → limits → links out).
• If the reader is DOING something end-to-end (a first send, a channel onboarding, a console walkthrough, a checklist), write a guide under guides/ with the first-visit skip conditions named.
• Every page — register the English path in docs.json in the same commit, run the pin, and never wire a locale-prefixed path into nav.