Example strategy and layout.

Cross-product guidance for where examples live, how they declare validation status, which CI and reviewer checks apply, and how examples map back to tutorials, guides, references, compatibility, limits, operations, and evidence.

Strategy Snapshot

Status labels: 4
Example lanes: 6
Validation gates: 7
Review state: Routed

Example Lifecycle

Pick SurfaceChoose whether the example belongs with a quickstart, guide, reference, compatibility row, limits page, operations page, or cross-product guide.
Create SourceAdd the example manifest, snippets, expected output, and evidence under docs/examples/{product}/{slug}/ when the example exists.
Declare StatusMark the example tested, manually verified, illustrative, or future before linking it from rendered docs.
Map PagesLink each example to the owning docs page, product hub, reference item, compatibility row, limit, and evidence record.
ValidateRun the current docs gates and any product smoke command that supports the claimed runnable behavior.
ReviewRoute product behavior, docs QA, platform, and sensitive-review triggers before strengthening the status.

Source Layout

Where examples and rendered pages live
Item	Path	Purpose	Owner
Layout contract	`docs/examples/README.md`	Defines the shared folder shape, manifest fields, status policy, page mapping, and validation expectations.	docs-product-lead
Product folder	`docs/examples/{product}/`	Groups examples for objectdb, message-broker, logdb, concordia, or cross-product workflows.	product docs owner
Example folder	`docs/examples/{product}/{example-slug}/`	Holds the source manifest, README, snippets, expected output, and evidence for one example.	example owner
Manifest	`manifest.yaml`	Declares product, status, language, owner, reviewers, docs pages, evidence, validation, and limits.	example owner
Rendered page	`/products/{product}/guides/{slug}/ or /guides/{slug}/`	Publishes context-rich examples where readers already expect the workflow or integration pattern.	docs page owner
Reference snippet	`/products/{product}/reference/{slug}/`	Embeds short examples beside the route, CLI, configuration, SDK, error, or limit item they demonstrate.	reference owner

Validation Status

Example status labels and proof requirements
Status	Meaning	Required proof	Link policy
`tested`	A docs or product command validates the exact example or an equivalent executable path.	Command, test, fixture, or script path plus covered behavior and reviewed output summary.	Can be linked from guides, references, quickstarts, and product hub next steps when relevant.
`manually-verified`	A reviewer ran the example or inspected output that matches the rendered page.	Reviewer note, date, environment class, and safe output summary.	Can be linked from guide pages when the reviewer-run rationale stays nearby.
`illustrative`	The snippet explains an API shape or pattern but is not meant to run as pasted.	Non-runnable rationale, source contract, and product SME acceptance.	Keep close to reference or guide text; do not use as quickstart proof.
`future`	The example describes a directional workflow that is not current runnable behavior.	Roadmap or concept evidence with explicit future maturity wording.	Keep out of quickstarts and current references unless the future label is visible.

Page Mapping

How examples map to docs surfaces
Docs surface	Example role	Mapping rule
Product quickstart	First-success proof and entry point.	Link only tested or manually verified examples that extend the quickstart without changing its result.
Product guide	Goal-oriented variation or integration pattern.	Place multi-step examples here when the reader needs context, decisions, or tradeoffs.
Product reference	Minimal route, CLI, config, SDK, error, or limit snippet.	Keep snippets small and tie each one to a reference item with maturity and evidence.
Compatibility matrix	Behavior boundary example.	Link examples only when they clarify supported, partial, unsupported, preview, future, or verification-required rows.
Limits page	Unsupported or caution example.	Use safe, minimal snippets to show what fails and where the reader should go next.
Operations page	Diagnostic or support evidence example.	Route through DOCS-056 when logs, traces, identifiers, support bundles, or privacy-sensitive fields appear.
Cross-product guide	Composition pattern.	Use only after every participating product surface has status, evidence, limits, and owner coverage.

CI Policy

Required checks for example PRs
Gate	Applies when	Requirement
`validate:examples`	Example source manifests exist or change.	Manifest status, rendered route links, evidence paths, validation modes, reviewers, and limits must pass.
`validate:docs-metadata`	Example source or rendered pages add publishable metadata.	Maturity values must use the allowed label set.
`validate:claim-lint`	Rendered pages include sensitive product or customer-facing wording.	Risky wording needs evidence, limits, or a documented waiver.
`validate:tutorial-smoke`	A quickstart or tutorial links an example as a runnable first-success path.	The linked tutorial keeps smoke coverage metadata current.
`validate:reference-schema`	A reference page embeds or links the example.	The referenced item still has examples, maturity, and evidence fields.
`Product smoke command`	The example claims runnable product behavior.	Product SME or docs QA records the command, output summary, and covered behavior.
`Manual review`	The example cannot run safely in docs CI.	The page names why manual verification is required and who reviewed it.

Work Item Map

Upcoming example lanes
Work item	Lane	Expected output	Owner
DOCS-058	ObjectDB S3 SDK examples	S3 client workflows for bucket create, object put/get/list, metadata or tags, and unsupported behavior notes.	objectdb-docs-owner
DOCS-059	Message Broker Rust SDK examples	Stream publish, replay, cursor, and queue worker flows with controlled-beta status.	message-broker-docs-owner
DOCS-060	LogDB OpenTelemetry Collector examples	Collector and curl examples for logs/traces ingest and query with tenant/auth headers and local-dev policy warnings.	logdb-docs-owner
DOCS-061	Concordia local curl examples	Cache, TSDB, Gateway alpha readiness, and active compatibility diagnostics.	concordia-docs-owner
DOCS-062	Cross-product community example	Illustrative community support architecture for attachment references, triage events, telemetry lookup, and local coordination boundaries.	docs-product-lead
DOCS-063	Example CI validation	Manifest validation gate for example status labels, rendered routes, evidence links, validation modes, reviewers, and limits.	docs-platform-owner

Review Gates

When examples need reviewer acceptance
Trigger	Required reviewers	Rule
Example names product behavior, route behavior, SDK symbols, CLI flags, config keys, or expected output.	Product SME and docs QA reviewer.	Keep the example verification-required until both accept the exact wording and status.
Example includes auth, tenant, dataset, bucket, object key, stream, trace, span, topology, logs, telemetry, or support-bundle evidence.	Product SME, docs QA reviewer, and affected sensitive reviewer.	Apply DOCS-056 and redact or replace sensitive values before publication.
Example changes navigation, source layout, generated code, or validation behavior.	Docs platform reviewer and docs lead.	Keep the platform change separate from product example content when possible.
Example is cross-product.	Docs product lead, docs QA reviewer, docs lead, and each affected product SME.	Every product surface needs a source page, maturity label, limits, owner, and evidence link.

Example Guardrails

Status First

Every example declares whether it is tested, manually verified, illustrative, or future before another page links to it.

One Owning Page

Each example has a primary docs page that owns context, limits, and navigation, even when snippets are reused elsewhere.

Source Stays Small

Use the docs example folder for manifests, snippets, expected output, and evidence notes; product repos still own executable product tests.

Evidence

DOCS-057 evidence map
Page area	Evidence	Status
Route and page mapping	DOCS-002	pending
Tutorial relationship and smoke metadata	DOCS-020 and DOCS-027	pending
Reference snippets and item evidence	DOCS-028	pending
Support and privacy-sensitive examples	DOCS-056	pending
Example source layout	docs/examples/README.md	pending
First product example source	DOCS-058 and docs/examples/objectdb/s3-sdk-examples/	pending
Second product example source	DOCS-059 and docs/examples/message-broker/rust-sdk-examples/	pending
Third product example source	DOCS-060 and docs/examples/logdb/otel-collector-examples/	pending
Fourth product example source	DOCS-061 and docs/examples/concordia/local-curl-examples/	pending
Cross-product example source	DOCS-062 and docs/examples/cross-product/community-support-snapshot/	pending
Example manifest validation	DOCS-063 and scripts/validate-example-manifests.mjs	pending

Limits

This guide does not add product examples, SDK packages, generated SDK references, product smoke scripts, or new CI jobs.
Do not mark an example tested unless a reviewer can point to an exact command, test, fixture, or script-backed equivalent.
Do not mark an example manually verified without reviewer identity, date, environment class, and safe output summary.
Do not use illustrative or future examples as quickstart proof.
Do not include real credentials, customer data, private topology, raw payloads, or support artifacts in example source.

Safe Next Steps

Available: DOCS-058
Review ObjectDB SDK examples
Use the first product example lane to review illustrative SDK status, source layout, and route evidence mapping.
Available: DOCS-059
Review Message Broker Rust SDK examples
Use the second product example lane to review tested Rust SDK status, source layout, and route maturity boundaries.
Available: DOCS-060
Review LogDB OpenTelemetry Collector examples
Use the third product example lane to review tested collector and curl status, source layout, and local policy boundaries.
Available: DOCS-061
Review Concordia local curl examples
Use the fourth product example lane to review tested curl status, source layout, and local alpha boundaries.
Available: DOCS-062
Review community support snapshot
Use the cross-product example lane to review illustrative architecture status, support evidence boundaries, and product role mapping.
Available: DOCS-063
Review example validation
Run and review the manifest validation gate for example status labels, rendered routes, evidence links, validation modes, reviewers, and limits.
Available: DOCS-064
Use search and filtering
Find examples, quickstarts, references, limits, and runbooks by product, maturity, content type, and audience.
Available: DOCS-065
Use version and status filtering
Compare docs surfaces by version or profile scope, maturity state, product, and evidence.
Available: DOCS-066
Use code tabs and copy controls
Use reusable tabs, copy buttons, and expected-output blocks on rendered examples.
Available: DOCS-092
Plan public feedback intake
Use the public feedback route for approved issue-template, support, redaction, page-health, privacy, and triage boundaries.
Available: DOCS-068
Use page health analytics
Track broken journeys, failed searches, page-feedback event shape review, stale pages, and no-result searches in the browser-local health dashboard.
Next: DOCS-069
Start accessibility and performance pass
Review accessibility, keyboard navigation, semantic headings, contrast, and page speed across the docs UX surfaces.
Available: DOCS-020
Use tutorial standards
Keep runnable first-success examples aligned with prerequisites, output, cleanup, troubleshooting, and smoke coverage.
Available: DOCS-028
Use reference schema
Tie short examples to route, CLI, config, SDK, error, and limit items with maturity and evidence.
Available: DOCS-056
Use support bundle privacy rules
Redact identifiers, telemetry, logs, and support evidence before examples quote operational output.