chore(docs): add 8.10 deployment journey IA proposal

[hisImminence]

Summary

• Adds docs/user journeys/8.10/8.10 deployment journey.md — a journey-shaped sidebar IA proposal for the Self-Managed 8.10 docs
• Reorganizes the sidebar from component-shaped (browse) to phase-shaped (act): Plan → Build Baseline → Extend → Day-2 → Migrate
• Includes full page-by-page migration table for all existing Self-Managed pages
• Content briefs for ~45 net-new pages required by the new structure (Appendix A)
• Rewrite guidance for existing pages that need changes beyond relocation (Appendix B)
• Competitor analysis validating the structure (Temporal, CockroachDB, Confluent)
• Three-phase rollout sequence ordered by risk and independent value

Test plan

• Review IA proposal with docs team
• Validate page migration tables against current sidebars.js
• Confirm scope with Hub team re: Hub/Console SM/Web Modeler consolidation
• Sign off before 8.10 GA documentation freeze

🤖 Generated with Claude Code

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://camunda.github.io/camunda-platform-helm/camunda-platform-helm/pr-preview/pr-6275/
Built to branch gh-pages at 2026-06-03 18:40 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[hisImminence]

Feedback incorporated — Hamza (round 1)

§1 Plan — reorder and rename

• Decision order changed: deployment target moves first (database options like OpenSearch are AWS-centric, so target must be decided before database; identity depends on both target and database)
• "Reference architectures" renamed to "Architecture diagrams" throughout; "blueprint" suffix dropped from sub-page names

§1 Plan — paradigm tab model (Option B)

• Pages that differ by deployment paradigm use Docusaurus tabs with groupId="deployment-paradigm" ([Kubernetes] / [Containers] / [Manual])
• Selecting a paradigm once persists across all pages in the session
• No nested tabs for cloud providers — too overwhelming; cloud providers remain as sidebar sub-pages with visual badges [AWS] [GCP] [Azure] [OpenShift] instead
• All tabbed pages annotated with paradigm badges in this proposal document so reviewers can see at a glance which pages carry tabs

§2 Baseline — full restructure into sequential numbered steps

Old shape had wrapper sections (Install / Common configuration) with paradigm sub-trees. New shape is flat numbered steps in logical provisioning order:

1. Provision infrastructure [Kubernetes] [Containers] [Manual]
   • K8s: cloud provider sub-pages (EKS / GKE / AKS / OpenShift+ROSA) + Kubernetes-specific config (ingress, gateway API, registry, pod networking, extra manifests)
   • Containers: Docker / AWS ECS
   • Manual: AWS EC2
2. Provision databases — PostgreSQL / ES-OS / Keycloak / Bitnami migration
3. Set up authentication — OIDC / Keycloak / basic auth
4. Install Camunda [Kubernetes] [Containers] [Manual]
   • License key, Secret management (only production-essential non-infra config)
   • Install Hub [tabs]
   • Install Orchestration Cluster [tabs] → Register OC in Hub (sub-step here, not a standalone page)
5. Production readiness checklist → Smoke test & exit criteria

Items removed from §2

Removed	Reason
"Separating Hub and Orchestration Cluster" page	Absorbed into Install Hub/Install OC install steps
"Helm v4 requirements" sidebar page	Becomes a prerequisite callout on the Install Camunda page
"Configure Camunda" step (step 5)	App configuration is a separate discussion; out of scope for the Baseline install journey
Chart parameters, application-configs, connectors, enable-additional-components, document handling	All out of Baseline scope — app config
"Register the OC in Hub" as standalone step	Moved inside Install Orchestration Cluster as final sub-step

[leiicamundi]

Thanks for putting this together — the journey-shaped direction, the competitor benchmarking, and the exhaustive page-by-page mapping make a strong foundation, and the risk-ordered phasing is the right instinct. A few cross-cutting suggestions, with specifics inline:

1. Anchor the diagnosis to an explicit baseline. The "current" shape described matches the Next (8.10) sidebars.js, not the released 8.9 sidebar; stating that up front prevents a false mismatch when reviewers check the live docs.
2. A couple of the flagged "problems" may be false positives — the OpenShift/ROSA "duplication" and the dual-region "misfiling" both look like distinct-target / deliberate-split situations on closer reading. Details inline.
3. Re-verify the external references (#5996–#5999, #7617, #8492); several resolve to unrelated or closed/held work today.
4. Evaluate navigability with a real draft. The structure is currently a written tree — a navigable preview (a sidebars.js branch / preview deploy of the reorganized sidebar) would let us judge findability and click-depth directly, which is hard to do from a mental model.
5. Size the work. The 50+/45+/15+ scope needs rough effort and owners per section to be plannable before GA.

None of this blocks the direction — these notes are about making the proposal easier to validate and land incrementally.

[leiicamundi]

A follow-up focused on the constructive / structural side, complementing the earlier factual notes. These are about the one area where the proposal risks reintroducing the problem it sets out to fix, plus two places where it's already aligned with good practice and worth reinforcing. Framed through Diátaxis (Tutorial / How-to / Reference / Explanation), which gives a per-page test — "what single user need does this serve?" — that the briefs can apply directly.

[leiicamundi]

A concrete Diátaxis-shaped variant (to avoid reinventing the wheel)

Most of the structural questions this proposal is working through — where do "concepts" stop and "reference" begin, why a catch-all section keeps forming, whether planning material is a journey step or standing content — are exactly what the Diátaxis framework already solves. Rather than deriving a bespoke taxonomy from competitor sites, it may be worth adopting Diátaxis's four needs (Tutorial / How-to / Reference / Explanation) as the organizing principle: it's a known, documented system, so the team inherits its rules and rationale instead of re-litigating them per section.

Applied to this proposal, the journey spine stays almost entirely intact — the only real change is splitting the one section that mixes two needs:

Self-Managed
├─ Get started            (Tutorial)        — Quickstart dev / admin
├─ Deploy to production   (How-to)          — Plan* → Deploy your baseline → Production checklist
├─ Operate                (How-to)          — was "Run and maintain": upgrades, backups, monitoring, scaling, troubleshooting
├─ Concepts               (Explanation)     — tenancy models, availability tiers, "when to use / when not to",
│                                              database-strategy trade-offs, identity model
├─ Reference              (Reference)       — architecture diagrams, topology blueprints, glossary,
│                                              chart parameters, supported environments
├─ Components             (Reference)       — per-component reference
└─ Migrate                (How-to)          — 8.9 → 8.10

What changes vs. the current §5:

• "Architecture and concepts" splits in two. Standing explanatory material (tenancy, tiers, "when to use / when not to") → Concepts; look-up material (architecture diagrams, topology blueprints, glossary, chart parameters) → Reference. This removes the new catch-all and dissolves the "Deployment concepts" level that appears in the briefs but not in the tree.
• "Plan your deployment" is recognized as Explanation, not a how-to step. The decision pages ("Choose your deployment target / database strategy / resilience tier") are explanatory; link them from the start of the how-to instead of embedding them in the install flow, so the action path stays a clean how-to.
• "Run and maintain" → "Operate" — same content, the name just signals the how-to intent (the doc already avoids "Operate" to dodge the app-name clash; that's a labeling call, not a structural one).
• The per-paradigm tab model is retained — it's the right answer to the deployment-paradigm × cloud-provider matrix and doesn't conflict with this split.

The payoff isn't a different tree — it's the per-page test the framework gives you: "what single need does this page serve — learn, do, look up, or understand?" That one question replaces section-by-section debate with a repeatable rule the content briefs can apply directly, and it's the missing criterion for deciding what goes where when the next ambiguous page shows up.

Everything the proposal already does well — the journey spine, the exhaustive page mapping, the competitor patterns (which are themselves largely Diátaxis-shaped) — carries over unchanged.

[hisImminence]

Adopted in full. 'Architecture and concepts' is split into Concepts (Explanation) and Reference (Reference) throughout the proposal. The Diátaxis framework is now stated explicitly in the document header as the organizing principle, with the per-page test ('what single need does this page serve?') as the decision rule going forward.

The one adjustment: 'Plan your deployment' stays as a how-to sub-section of Deploy to production rather than moving to Explanation, since it's action-gated (you make the decision in order to proceed with the install). The decision pages within it (Choose your resilience tier, Choose your identity strategy, etc.) are explanation-shaped, and they cross-link to the deeper Concepts pages for users who want the full trade-off depth.

'Run and maintain' name is kept over 'Operate' to avoid confusion with the Operate application — agreed this is a labeling call, not a structural one.