If two CreatorCommerce docs appear to overlap, this page explains which one wins. For facts and stable technical detail, canonical reference pages win over summaries.
Canonical Rule
CreatorCommerce docs are intentionally split by job:
- Overview pages explain what something is and when to use it.
- How-to pages explain implementation order and execution steps.
- Reference pages hold canonical facts.
- Use-case pages route you to the right references.
- AI playbooks help assistants reason about workflows, but they should cite canonical docs instead of restating them as truth.
Page Types
| Page type | Purpose | What belongs there | What does not |
|---|
| Overview | Orientation and decision framing | Concepts, tradeoffs, system maps, capability summaries | Full field lists, endpoint catalogs, canonical payloads |
| How-to | Implementation guidance | Steps, sequencing, setup, migration, QA | Full schema definitions duplicated from references |
| Reference | Source-of-truth technical detail | Fields, selectors, stable variables, event payloads, auth details, endpoint groups | Broad strategy or marketing framing |
| Use-case page | Fast routing by task | What you can do, where to go next, best references | Deep technical detail that already lives elsewhere |
| AI playbook | AI workflow guidance | Prompt patterns, reasoning guardrails, task framing | Competing copies of canonical technical facts |
pageType.
Path Ownership
These path conventions determine default page type ownership across the live docs:
| Path or pattern | Default page type |
|---|
references/** | Reference |
ai-guides/** | AI playbook |
guides/dev/** | Use-case page |
use-cases/** | Overview or routing page |
guides/**/overview | Overview |
guides/storefronts/**, guides/emails/**, guides/enrichment/**, guides/creator-experience/**, guides/integrations/build/** | How-to by default unless explicitly framed as an overview |
Canonical Homes for High-Value Domains
Authoring Rules
- Add or update canonical facts in the reference page first.
- If an overview or how-to page needs the same fact, summarize it and link to the canonical reference instead of restating it in full.
- Do not publish placeholder pages, planning notes, or draft stubs in live navigation.
- Do not link public docs to repo-local implementation notes or private file paths.
- If a new concept introduces stable product vocabulary, update the glossary.
- If a new feature changes downstream implementation behavior, update both the canonical reference and the relevant use-case or how-to routing page.
Required Cross-Links
Every new feature or capability should link outward in a predictable way:
- Overview page links to the canonical reference and at least one how-to page.
- How-to page links back to the overview and the canonical reference.
- Reference page links to the nearest overview or how-to page for context.
- AI playbook links to the canonical reference pages it expects an assistant to trust.
Update Workflow
When shipping a new feature, capability, or data-model change:
- Update the canonical reference page first.
- Update overview and how-to pages that summarize or implement that feature.
- Update the glossary if naming or meaning changed.
- Update AI playbooks only if the prompting pattern or recommended workflow changed.
- Add a release note if the change is externally meaningful.
- Verify links, nav placement, and page-type fit before publishing.
Validation Checklist
- Every live page declares
pageType in frontmatter.
- No placeholder or draft content in the live docs.
- No conflicting copies of canonical facts across guides.
- Internal links resolve to the active docs tree.
- API endpoint details come from the generated OpenAPI surfaces.
- Legacy or archived material is clearly marked non-canonical.
