Skip to main content

​
Objectives

  • provide zero-to-hero comprehension paths
  • preserve technical correctness while remaining product-focused
  • align content with real user roles and operational goals

​
IA Model

Primary docs areas are role- and intent-driven:
  • Home / About for orientation and core concepts
  • Community for ecosystem participation
  • Developers / Gateways / Orchestrators / Delegators for role workflows
  • Resources for references, guides, and internal docs tooling
Navigation source files:
  • docs.json
  • v2/pages/**

​
Content Layers

​
Layer 1: Product and Positioning

  • value proposition and context framing
  • user journey entry points
  • concise decision-oriented summaries

​
Layer 2: Operational How-to

  • setup, runbooks, migration/checklist pages
  • practical workflows with expected outcomes

​
Layer 3: Deep Reference

  • APIs, schema/spec docs, command matrices, component details
  • troubleshooting and edge-case documentation

​
Copy + Quality Principles

  • maintain product clarity without sacrificing technical precision
  • prefer canonical references over duplicated procedural text
  • ensure claims are traceable to code, workflow config, or primary docs
  • keep docs maintainable through automation + validation

​
Canonical Supporting Docs

  • Public docs guide pages:
    • v2/resources/documentation-guide/documentation-guide.mdx
    • v2/resources/documentation-guide/style-guide.mdx
    • v2/resources/documentation-guide/component-library.mdx
    • v2/resources/documentation-guide/contribute-to-the-docs.mdx
    • v2/resources/documentation-guide/snippets-inventory.mdx
  • Internal navigation/governance:
    • docs-guide/overview.mdx
    • docs-guide/policies/source-of-truth-policy.mdx
Contributor-facing authoring helpers now live in the public documentation-guide pages, not in docs-guide/tooling/dev-tools.mdx.

​
Maintainer Guidance

When adding new content surfaces:
  1. Place content in the correct IA layer and role context.
  2. Add or update navigation in docs.json where appropriate.
  3. Add automation hooks/index generation only when repeatability is clear.
  4. Update docs-guide maps so maintainers can discover and govern the feature.

​
Publishable vs Workspace Material

V2 sections now have an explicit distinction between publishable page trees and maintainer-only workspace material:
  • Publishable docs live in normal section trees and are intended for docs.json routing.
  • Planning, research, handoff, and review material belongs in governed non-publishable lanes.
  • The canonical path contract lives in docs-guide/policies/v2-folder-governance.mdx.
Use the folder governance policy when deciding whether a file belongs in the live IA or in a section workspace lane.
Last modified on March 16, 2026