mirror of
https://github.com/coder/coder.git
synced 2026-10-16 14:48:56 +08:00
Nick Vigilante
d5a6047879
Restructures the Install section into the five-phase deployment spine, so the reading order matches the order a deployment actually happens: **plan, prepare, install, validate, operate.** Today the first thing a reader sees is a shell command, and architecture and sizing sit downstream in Administration, after the point where they would have been useful. Resolves [DOCS-869](https://linear.app/codercom/issue/DOCS-869). Part of [DOCS-685](https://linear.app/codercom/issue/DOCS-685) and [DOCS-738](https://linear.app/codercom/issue/DOCS-738). > [!IMPORTANT] > **Stacked on [#28960](https://github.com/coder/coder/pull/28960)** (DOCS-871, terminology). Base is that branch, not `main`. Retarget to `main` after it merges. > > **Paired with coder/coder.com [#1077](https://github.com/coder/coder.com/pull/1077)**, which must merge **first**. Without it, every inbound link to a moved page 404s in the gap. ## Deliberately mechanical No prose changes. The only edits inside moved pages are relative link and image path repairs, so the diff reads as renames. That is the point: this is the highest link-breakage change in the project, and it should be reviewable as such. The prose work is [DOCS-868](https://linear.app/codercom/issue/DOCS-868) (phase overview, architecture rewrite, sizing split, actor table) and [DOCS-872](https://linear.app/codercom/issue/DOCS-872) (new pages). ## The new spine ```text Install and deploy Coder /install ├── Coder CLI [unchanged, retired by DOCS-870] ├── 1. Plan your deployment │ ├── Architecture and components [from admin/infrastructure] │ └── Coder Validated Architecture [from admin/infrastructure] │ └── 1k / 2k / 3k / 10k users ├── 2. Prepare prerequisites │ ├── Licensing [from admin/licensing] │ ├── Air-gapped deployments [from install/airgap] │ └── Mirror images and registries [from install/registry-mirror-artifactory] ├── 3. Install the control plane │ ├── Docker / Kubernetes / Rancher / OpenShift │ ├── Cloud marketplace and VM images │ └── Unofficial install methods ├── 4. Validate your deployment │ └── Scale testing [from admin/infrastructure] │ ├── Scale test utility │ └── Scaling best practices └── 5. Operate and maintain ├── External provisioners [from admin/provisioners] ├── Upgrading (+ best practices, ESR guides) └── Uninstall ``` Leaving Install: release channels become `reference/releases`, feature stages become `reference/feature-stages`. `docs/admin/infrastructure/` is gone entirely, which is what DOCS-738 recommended. ## Numbers - 31 pages moved, all as `git mv` renames. - 1 page deleted: `admin/infrastructure/index.md`, whose content was a one-line section blurb. - 5 new placeholder index pages, one per phase, each a sentence of orientation plus `<children></children>`. The nav schema requires a path on every entry, so a phase cannot exist without one. - 265 relative links and asset paths repaired across 57 files. - `docs/manifest.json` restructured. Entry count goes 460 to 464: plus 5 stubs, minus the deleted Infrastructure entry. ## Reviewer attention, please **The redirects PR repairs 19 existing redirects, not just adds new ones.** This was the surprise. `redirects.json` already had entries whose *destinations* pointed at pages this PR moves, so they would have started redirecting to 404s. Examples: `/docs/architecture/architecture`, `/docs/admin/architectures`, `/docs/scaling/scale-testing`, `/docs/licensing`, `/docs/enterprise`, `/docs/install/offline`, `/docs/platforms`, `/docs/install/1-click`, `/docs/admin/upgrade`, `/docs/install/cloud/ec2`, and both `feature-stages` aliases. All 19 are fixed in the paired PR. **This PR touches `scripts/`, so it is not docs-only.** Two release tools write to paths that moved and would have broken silently at release time: - `scripts/update-release-calendar.sh`: `DOCS_FILE` now points at `docs/reference/releases.md`. - `scripts/releaser/docs.go`: `releasesFile`, and also `kubernetesFile` and `rancherFile`, which pointed at `docs/install/kubernetes.md` and `docs/install/rancher.md`. <details> <summary>Deliberate scope decisions</summary> - **Self-managed vs cloud grouping is flattened.** The reconciled IA nested platform pages under a "Self-managed platforms" parent. That would need two more placeholder index pages for groups with no content yet, so the platform pages sit directly under Phase 3 and the grouping lands with the DOCS-868 prose. - **Release-notes URLs left alone.** `scripts/releaser/release.go` and `scripts/release/generate_release_notes.sh` embed `https://coder.com/docs/install/releases` and `/docs/install/upgrade` in release-note templates. The redirects cover them, and changing the strings would require updating Go test fixtures in `scripts/release/main_internal_test.go`. Better as its own change. - **In-product doc links left alone.** Several `site/src` pages link to `coder.com/docs/admin/provisioners` and similar. Those are absolute URLs, so the redirects cover them. Updating them is a frontend change that would pull frontend review into a docs restructure. - **`admin/security/audit-logs.md` line 237** is hand-written prose below the generated table, and its `../licensing/index.md` link had to move with the licensing page. Verified `make gen` does not revert it. - **`reference/feature-stages.md`** has generated blocks whose relative links changed depth with the move. The generator named in its own marker comment (`scripts/release/docs_update_feature_stages.sh`) no longer exists in the repo, so those links were repaired by hand and the file is effectively hand-maintained. Worth its own issue. - **`install/cli.md` keeps its nav slot** here. DOCS-870 retires it. </details> ## Verification | Check | Result | |---|---| | Broken relative link scan | 0 in `install/`, `admin/`, `reference/`. 21 remain, all pre-existing illustrative examples in `docs/.style/style-guide/**` and one malformed URL in `docs/README.md` | | `make gen` | clean, manifest not clobbered, phase structure intact | | `make lint/markdown` | pass, 508 files, 0 errors | | `make lint/emdash` | pass | | `make lint/docs-html` | pass | | `make lint/prose` | pass, 1 intentional demo error, no new findings | | `make pre-commit` | pass, including `lint/go`, `lint/ts`, `lint/shellcheck`, and a slim build | | Manifest audit | every path resolves to a file on disk; entry-by-entry diff shows only the expected moves | Generated with Coder Agents on behalf of @nickvigilante. <details> <summary>CI note: doc-check failure is infrastructure, not this PR</summary> `Analyze PR for Documentation Updates Needed` fails before it reviews anything: the Coder account behind `agents-chat-action` returns `User is not active (status = "suspended")`. It isn't a required check. `check-docs` (linkspector) and every other check pass on `58ed9e3e4b`. _CI note added by Coder Agents on behalf of @nickvigilante._ </details>