Skip to content

Administration IA phase 2: Give self-hosting the same shelves #21053

Description

@jkodroff

Phase 2 of the Administration IA restructure. Give self-hosting/ the same five shelves the rest of the docs use, one level down.

Self-hosting stays nested rather than dissolving into the top-level shelves: it's a distinct audience doing a distinct job (installing and running software), and its 25 pages would swamp the SaaS content if merged. Precedent for a nested section carrying its own IA: insights/discovery/get-started/.

Pure git mv + alias. No prose edits, except where a merge is called out below.

All paths relative to content/docs/administration/self-hosting/.

get-started/

Current Proposed
deployment-options/quickstart-docker-compose.md get-started/quickstart-docker-compose.md

Needs a get-started/_index.md.

concepts/ — what the thing is before you install it

Current Proposed
operations/architecture.md concepts/architecture.md
components/_index.md concepts/components/_index.md
components/api.md concepts/components/api.md
components/console.md concepts/components/console.md
components/deployments.md concepts/components/deployments.md
components/search.md concepts/components/search.md
network.md concepts/network-requirements.md

network.md currently carries the link title "Network reqs" — fix the abbreviation while renaming.

guides/ — how to install it

Six of the eight deployment pages are named *-hosted and two aren't. deploy-on-* makes the set consistent and reads better in the sidebar.

Current Proposed
deployment-options/eks-hosted.md guides/deploy-on-eks.md
deployment-options/aks-hosted.md guides/deploy-on-aks.md
deployment-options/gke-hosted.md guides/deploy-on-gke.md
deployment-options/ecs-hosted.md guides/deploy-on-ecs.md
deployment-options/local-docker.md guides/deploy-on-local-docker.md
deployment-options/byo-infra-hosted.md guides/deploy-on-byo-infra.md
airgapped.md guides/air-gapped.md
saml-sso.md guides/configure-saml-sso.md

deployment-options/_index.md is retired — alias it to guides/. Its deployment-option cards should be rebuilt on the new guides/_index.md.

⚠️ saml-sso.md (492 words) duplicates material in administration/guides/saml/ (nine pages, moved in Phase 1). Reconcile into one guide with a self-hosted section rather than carrying both forward. This is the one content change in this phase — if it turns into a real rewrite, split it out and let the plain move land first.

operations/ — unchanged

Already the right shelf. These 9 files stay exactly where they are: _index, backup-recovery, compute-sizing, database, monitoring, networking, object-storage, security-hardening, upgrades.

reference/

Current Proposed
changelog.md reference/changelog.md

Also

self-hosting/_index.md stays put but its card lists point at the old paths — rebuild them against the new structure. Menu label casing is inconsistent here too: "Self-Hosting" in the parent card vs. "Self-hosting" in the page title.

Acceptance

  • 18 files moved with /move-doc; the 9 operations/ files untouched
  • Every pre-existing alias preserved — self-hosting/_index.md alone carries six historical paths back to /docs/guides/self-hosted/
  • deployment-options/_index.md aliased to guides/, not deleted
  • self-hosting/_index.md cards rebuilt against new paths
  • Duplicate self-hosted SAML page reconciled with guides/saml/ (or split out to its own issue)
  • make lint passes
  • Alias verification pass clean

Depends on Phase 1. Part of the Administration IA epic. Proposal with full rationale: https://claude.ai/code/artifact/3dfed61d-a02c-4feb-9f9d-c77d7b33accb

Metadata

Metadata

Assignees

Labels

area/automationIssues relating to automation (mostly GHA workflows) and automatically generated contentarea/docs-contentIssues relating to content under pulumi.com/docskind/taskresolution/fixedThis issue was fixed

Type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions