Doc Placement Guide

This page tells contributors where new ADK documentation pages belong. It is the operational counterpart to Documentation Standards: standards covers how to write a page (style, audience markers, claim hygiene); placement covers where the page goes in the sidebar so operators can find it.

The two axes

Every new doc page is classified along two axes before it is filed:

1. Audience intent — what is the reader trying to do?

2. Distribution mode — does the page describe CE, Controlled, or shared behavior?

Both axes have to be answered before a page lands. If a contributor can’t answer either one cleanly, the page is probably overscoped and should be split.

Axis 1 — Audience intent (top-level sidebar group)

Audience	Top-level group	Concrete example
Evaluator — just wants to see if ADK works	Evaluate	2-Minute CE Demo (docs/quickstart.md)
Operator deploying for real — installing the binary, bringing up the first stack	Install & Run	CE First Stack, Controlled First Stack, Robotics CE First Stack
Engineer / learner — wants to understand a concept end-to-end with reproducible inputs and outputs	Tutorials → CE Concepts / Validation Evidence	01-single-node-receive-verify-activate, rollout-latency-validation
Operator under fire — needs to type a command right now to recover, advance a stage, or run a drill	Runbooks	demo-runbook, 01-fleet-rollout-recovery, 11-emergency-rollback
Architect / integrator — wants to understand boundaries, contracts, capabilities	Architecture & Design	architecture/overview, security-model
Auditor / reviewer — wants to trace a claim to evidence	Tutorials → Validation Evidence + Traceability	Any *-proof-report-validation.md, traceability/invariant-map
Stack reference — wants to know what runs and how the pieces fit	Demo Stack Reference	demo/ros2-governance, demo/gazebo-simulation

Tutorials vs Runbooks — the cleanest separation

Tutorials teach or validate expected behavior. Tone is indicative and demonstrative: here is how it works; here is the evidence it works. Audience is calm, learning, or producing evidence.

Runbooks tell operators what to do during bring-up, incidents, failures, drills, or recovery. Tone is imperative: run X; check Y; if Z, then…. Audience is under time pressure, sometimes under fire.

If your page says “run this command, then this one, and if the output says X then do Y,” it is a runbook regardless of what the topic is. The Demo Runbook is the canonical example: it walks step-by-step through make demo-up / make demo-run including failure drills, so it lives under Runbooks, not Demo (which is the reference surface).

Installed: the same Demo Runbook documents the installed-operator equivalents (bash demo/scripts/demo_up.sh and the three numbered scripts under demo/scripts/0{1,2,3}.sh) in its “Operator paths” preamble — so the placement rule is independent of the form the operator runs the commands in.

Group composition rules (anti-drift)

The audience mapping above only works if each group keeps a single, clear shape. These rules (from the #742 reorg) stop groups from sliding back into overloaded buckets and junk-drawers:

• Reference is look-up only. It holds the surface of a thing — CLI flags, API endpoints, config keys, artifact/bundle formats (cli, gui, api, config, oci, policy). How-to / operator-guide content (e.g. “how to set config values”, “how to set up tracing/metrics”) goes to Runbooks, not Reference — even when the topic is “configuration” or “observability”.

• No junk-drawer. There is no “Additional” group. Every page belongs to a group whose shape it matches; if none fits, the page’s shape is unclear — fix the page, don’t add a catch-all group.

• One path per topic. A topic appears at exactly one sidebar path. When a topic has both a section (x/index.md) and a legacy standalone page (x.md), make the section canonical and re-parent the standalone under it (add ../x to the section’s {toctree}) rather than listing both at the top level. This is why security-model.md sits under Architecture & Design → Security and traceability.md under Development → Traceability.

• CLI reference is generated. docs/_generated/cli{,-ce}/ pages come from the clidocs generator (make docs-cli-gen); never hand-edit them. The hand-written docs/cli/*.md are curated overviews titled “ — CLI overview” so they don’t collide with the generated root pages (enforced by scripts/ci/cli-docs-h1-guard.sh).

sphinx-build -W fails on broken links, orphan pages, and a page listed in two toctrees, so a duplicate or mis-move is caught in CI.

Axis 2 — Distribution mode (page classification)

Every page that teaches how to run this identifies whether it is:

• CE — applies to local / single-node Community Edition artifacts, no orchestrator, no fleet, no Commercial Agreement.

• Controlled — applies to the partner/customer Controlled Deployment path: orchestrator-managed, fleet topology, staged rollout, audit/compliance workflows, Commercial Agreement.

• Shared — applies to both CE and Controlled (e.g. the runtime contract, the policy model, the policy bundle format, supply-chain verification semantics).

Mark the classification one of three ways:

1. In the sidebar caption — preferred for new top-level groups. Example: CE Operator Runbooks, Controlled Deployment Runbooks.

2. In the page title — preferred when the page is a single-mode landing page. Example: Controlled First Stack, Robotics CE First Stack.

3. In an audience banner at the top of the page — preferred when the page is mostly shared but has CE-specific or Controlled-specific sections. Use a callout block.

Terminology — do not use “Paid” / “Premium” / “Pro” / “Enterprise” as user-facing labels. The distinction is operational and governance-maturity, not pricing. “Controlled” denotes managed, auditable, partner/customer deployment with explicit operational controls. The internal Sphinx tier tag remains paid for build-time conditionals (see conf.py and the {only} paid blocks); only the user-facing language is “Controlled”.

Worked examples on current ADK pages

Page	Audience intent	Distribution mode	Where it lives	Why
docs/quickstart.md	Evaluator	CE	Evaluate → 2-Minute CE Demo	One screen, one install one-liner, evaluator decides whether to keep looking.
docs/getting-started/quickstart-robotics.md	Operator deploying for real	CE (robotics)	Install & Run → Robotics CE First Stack	Real bring-up of the robotics demo stack on local artifacts.
docs/getting-started/orchestrator-saas.md	Operator deploying for real	Controlled	Install & Run → Controlled First Stack	Partner/customer orchestrator path; requires Commercial Agreement.
docs/tutorials/01-single-node-receive-verify-activate.md	Engineer / learner	CE	Tutorials → CE Concepts	Teaches the single-node receive→verify→activate flow on CE artifacts, end-to-end.
docs/tutorials/rollout-latency-validation.md	Auditor / reviewer	Shared	Tutorials → Validation Evidence	Reproducible-input, reproducible-output evidence artifact.
docs/runbooks/demo-runbook.md	Operator under fire	CE	Runbooks → CE Operator Runbooks	Step-by-step bring-up + failure drills for the demo stack.
docs/runbooks/01-fleet-rollout-recovery.md	Operator under fire	Controlled	Runbooks → Controlled Deployment Runbooks	Recovery procedure for orchestrator-managed fleet rollout.
docs/demo/ros2-governance.md	Stack reference	Shared	Demo Stack Reference	Reference material for ROS 2 governance integration; not a walkthrough.

What to do when a page doesn’t fit

If you can’t classify a page along both axes, the page is probably overscoped. Common patterns:

• “This page teaches a concept AND tells you what to do during an incident.” — Split into a tutorial (concept) and a runbook (procedure). Cross-link them.

• “This page applies to both CE and Controlled but the steps diverge midway.” — Either split into two pages with a shared intro, or use an audience-banner-per-section approach. The shared-intro split is usually cleaner because it survives future divergence.

• “This page is reference material AND a walkthrough.” — Reference goes under Demo Stack Reference or Architecture & Design. Walkthrough goes under Install & Run, Tutorials, or Runbooks depending on the audience-intent axis.

When to update this guide

Update this page when:

• A new top-level sidebar group is added or renamed.

• The CE / Controlled distinction extends to a new artifact type.

• A new placement edge case is encountered that future contributors will hit (a one-line worked example is usually enough).