coder
diff --git a/‎.claude/docs/DOCS_STYLE_GUIDE.md‎
Lines changed: 21 additions & 10 deletions b/‎.claude/docs/DOCS_STYLE_GUIDE.md‎
Lines changed: 21 additions & 10 deletions
diff --git a/‎docs/_redirects‎
Lines changed: 0 additions & 13 deletions b/‎docs/_redirects‎
Lines changed: 0 additions & 13 deletions
@@ -6,7 +6,7 @@ This guide documents documentation patterns observed in the Coder repository, ba
 
 Before documenting a feature:
 
-1. **Research similar documentation** - Read recent documentation pages in `docs/` to understand writing style, structure, and conventions for your content type (admin guides, tutorials, reference docs, etc.)
+1. **Research similar documentation** - Read 10+ similar pages in `docs/` to understand writing style, structure, and conventions for your content type (admin guides, tutorials, reference docs, etc.)
 2. **Read the code implementation** - Check backend endpoints, frontend components, database queries
 3. **Verify permissions model** - Look up RBAC actions in `coderd/rbac/` (e.g., `view_insights` for Template Insights)
 4. **Check UI thresholds and defaults** - Review frontend code for color thresholds, time intervals, display logic
@@ -42,7 +42,10 @@ Template Insights provides detailed analytics and usage metrics for your Coder t
 
 ### Premium Feature Callout
 
-For Premium-only features, add `(Premium)` suffix to the H1 heading. The documentation system automatically links these to premium pricing information. You should also add a premium badge in the `docs/manifest.json` file with `"state": ["premium"]`.
+For Premium-only features:
+
+1. Add `(Premium)` suffix to the H1 heading - the documentation system automatically links these to premium pricing information
+2. Add premium badge in `manifest.json` with `"state": ["premium"]`
 
 ```markdown
 # Template Insights (Premium)
@@ -91,7 +94,7 @@ When you have multiple screenshots showing different aspects of a feature:
 
 ### Screenshot Guidelines
 
-**When screenshots are not yet available**: If you're documenting a feature before screenshots exist, you can use image placeholders with descriptive alt text and ask the user to provide screenshots:
+**When screenshots are not available**: Use image placeholders with descriptive alt text and ask the user to provide screenshots:
 
 ```markdown
 ![Placeholder: Template Insights page showing weekly active users chart](../../images/admin/templates/template-insights.png)
@@ -131,7 +134,7 @@ Then ask: "Could you provide a screenshot of the Template Insights page? I've ad
  - `> [!NOTE]` for additional information
  - `> [!WARNING]` for important warnings
  - `> [!TIP]` for helpful tips
-- **Tabs**: Use tabs for presenting related but parallel content, such as different installation methods or platform-specific instructions. Tabs work well when readers need to choose one path that applies to their specific situation.
+- **Tabs**: Use tabs to present related but parallel documentation paths (e.g., different installation methods, platform-specific instructions)
 
 ## Writing Style
 
@@ -160,19 +163,17 @@ Then ask: "Could you provide a screenshot of the Template Insights page? I've ad
 
 ### Command Examples
 
-````markdown
+Use `sh` language for shell commands:
+
 ```sh
 coder server --disable-template-insights
 ```
-````
 
 ### Environment Variables
 
-````markdown
 ```sh
 CODER_DISABLE_TEMPLATE_INSIGHTS=true
 ```
-````
 
 ### Code Comments
 
@@ -189,8 +190,6 @@ Use relative paths from current file location:
 - `[Template Permissions](./template-permissions.md)`
 - `[API documentation](../../reference/api/insights.md)`
 
-For cross-linking to Coder registry templates or other external Coder resources, reference the appropriate registry URLs.
-
 ### Cross-References
 
 - Link to related documentation at the end
@@ -300,10 +299,22 @@ Some content is auto-generated with comments:
 
 Don't manually edit auto-generated sections.
 
+## URL Redirects
+
+When renaming or moving documentation pages, redirects must be added to prevent broken links.
+
+**Important**: Redirects are NOT configured in this repository. The coder.com website runs on Vercel with Next.js and reads redirects from a separate repository:
+
+- **Redirect configuration**: https://github.com/coder/coder.com/blob/master/redirects.json
+- **Do NOT create** a `docs/_redirects` file - this format (used by Netlify/Cloudflare Pages) is not processed by coder.com
+
+When you rename or move a doc page, create a PR in coder/coder.com to add the redirect.
+
 ## Key Principles
 
 1. **Research first** - Verify against actual code implementation
 2. **Be precise** - Use exact numbers, permission names, API paths
 3. **Visual structure** - Organize around screenshots when available
 4. **Link everything** - Related docs, API endpoints, CLI references
 5. **Manifest inclusion** - Add to manifest.json for navigation
+6. **Add redirects** - When moving/renaming pages, add redirects in coder/coder.com repo