mirror of
https://github.com/coder/coder.git
synced 2026-09-21 12:44:32 +08:00
Nick Vigilante
73af2ca632
## What Audit and fix the page `description` fields in `docs/manifest.json` so each one is accurate, unique, and follows meta-description SEO best practices, targeting 70-155 characters. Tracking: DOCS-576 ## Why Many manifest descriptions were terse (243 of 272 hand-maintained descriptions were under 70 characters), a few reused another page's description (copy/paste errors), and one just repeated its own title. These feed the per-page `<meta name="description">` on coder.com/docs, so they matter for search snippets and click-through. ## What changed The manifest diff is +244 / -244 lines, touching only `description` string values (0 structural lines changed). A second commit regenerates one downstream file (see Generated file below). - **Fixed 5 copy/paste errors** where a page reused another page's description: - `admin/monitoring/index.md` (had Security's text) - `admin/monitoring/metrics.md` (had Logs' text) - `admin/templates/template-permissions.md` (had "Creating Templates" text) - `admin/networking/stun.md` (had Port Forwarding's text) - `admin/provisioners/manage-provisioner-jobs.md` (had the provisioners index text) - **Fixed `reference/index.md`**, whose description merely repeated the title "Reference". - **Corrected wording**: "Coderd API" to Coder REST API; "VSCode" to VS Code; dropped the `&` shorthand on the AI Gateway index per the docs style guide. - **Corrected accuracy**: the AI landing page listed outdated example agents (GPT-Code, OpenDevin, SWE-Agent); it now references agents used elsewhere in the docs (Claude Code, Aider). - **Expanded terse descriptions** into the 70-155 range with active-voice, front-loaded phrasing. ## Generated file `docs/install/releases/feature-stages.md` is generated by `scripts/release/docs_update_feature_stages.sh`, which copies the beta pages' manifest descriptions verbatim into the beta-features table. Three rows (MCP Server, JetBrains Toolbox, Coder Agents) update to match the new descriptions; User secrets is unchanged. Regenerated with `make gen` so the generated-files check stays clean. ## Scope / exclusions Auto-generated reference subtrees are intentionally left untouched, since `make gen` rebuilds them from source and would revert hand edits (and fail the generated-files check): - `Reference > Command Line` children, from `scripts/clidocgen` (each command's `Short` help) - `Reference > REST API` children, from `scripts/apidocgen` - `Reference > Agent API` children The section index nodes themselves (Reference, REST API, Command Line, Agent API) are hand-maintained and are in scope. ## Validation - `docs/manifest.json` is valid JSON; diff touches only `description` values. - All 272 in-scope descriptions are now 70-155 characters, with 0 duplicates across distinct pages. - No double quotes, backslashes, em/en dashes, or `&` / `<` / `>` in descriptions. - Biome 2.4.10 (`scripts/biome_format.sh`) is a no-op on the result. - `scripts/check_emdash.sh` passes. > This PR was created with AI assistance (Coder Agents).