This guide documents documentation patterns observed in the Coder repository, based on analysis of existing admin guides, tutorials, and reference documentation. This is specifically for documentation files in the `docs/` directory - see [CONTRIBUTING.md](../../docs/about/contributing/CONTRIBUTING.md) for general contribution guidelines.

Before documenting a feature:

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

5. **Cross-reference with tests** - Test files document expected behavior and edge cases

6. **Verify API endpoints** - Check `coderd/coderd.go` for route registration

When documenting features, always verify these implementation details:

- Read handler implementation in `coderd/`

- Check permission requirements in `coderd/rbac/`

- Review frontend components in `site/src/pages/` or `site/src/modules/`

- Verify display thresholds and intervals (e.g., color codes, time defaults)

- Confirm API endpoint paths and parameters

- Check for server flags in serpent configuration

**H1 heading**: Single clear title without prefix

# Template Insights

**Introduction**: 1-2 sentences describing what the feature does, concise and actionable

Template Insights provides detailed analytics and usage metrics for your Coder templates.

For Premium-only features, add `(Premium)` suffix to the H1 heading. The documentation system automatically links these to premium pricing information.

# Template Insights (Premium)

Common pattern after introduction:

## Overview

Template Insights offers visibility into:

- **Active Users**: Track the number of users actively using workspaces

- **Application Usage**: See which applications users are accessing

Use bold labels for capabilities, provides high-level understanding before details.

**Place images after descriptive text**, then add caption:


<small>Template Insights showing weekly active users and connection latency metrics.</small>

- Image format: ``

- Caption: Use `<small>` tag below images

- Alt text: Describe what's shown, not just repeat heading

When you have multiple screenshots showing different aspects of a feature:

1. **Structure sections around images** - Each major screenshot gets its own section

2. **Describe what's visible** - Reference specific UI elements, data values shown in the screenshot

3. **Flow naturally** - Let screenshots guide the reader through the feature

**Example**: Template Insights documentation has 3 screenshots that define the 3 main content sections.

**When screenshots are not available**: Use image placeholders with descriptive alt text and ask the user to provide screenshots:


Then ask: "Could you provide a screenshot of the Template Insights page? I've added a placeholder at [location]."

**When documenting with screenshots**:

- Illustrate features being discussed in preceding text

- Show actual UI/data, not abstract concepts

- Reference specific values shown when explaining features

- Organize documentation around key screenshots

1. **H2 (##)**: Major sections - "Overview", "Accessing [Feature]", "Use Cases"

2. **H3 (###)**: Subsections within major sections

3. **H4 (####)**: Rare, only for deeply nested content

- **Accessing [Feature]**: How to navigate to/use the feature

- **Use Cases**: Practical applications

- **Permissions**: Access control information

- **API Access**: Programmatic access details

- **Related Documentation**: Links to related content

- **Unordered lists**: Non-sequential items, features, capabilities

- **Ordered lists**: Step-by-step instructions

- **Tables**: Comparing options, showing permissions, listing parameters

- **Callouts**:

- `> [!NOTE]` for additional information

- `> [!WARNING]` for important warnings

- `> [!TIP]` for helpful tips

- **Direct and concise**: Avoid unnecessary words

- **Active voice**: "Template Insights tracks users" not "Users are tracked"

- **Present tense**: "The chart displays..." not "The chart will display..."

- **Second person**: "You can view..." for instructions

- **Consistent terms**: Use same term throughout (e.g., "workspace" not "workspace environment")

- **Bold for UI elements**: "Navigate to the **Templates** page"

- **Code formatting**: Use backticks for commands, file paths, code

- Inline: `` `coder server` ``

- Blocks: Use triple backticks with language identifier

- **Numbered lists** for sequential steps

- **Start with verb**: "Navigate to", "Click", "Select", "Run"

- **Be specific**: Include exact button/menu names in bold

```sh

coder server --disable-template-insights

Document exact values from code:

- **Thresholds**: "green < 150ms, yellow 150-300ms, red ≥300ms"

- **Time intervals**: "daily for templates < 5 weeks old, weekly for 5+ weeks"

- **Counts and limits**: Use precise numbers, not approximations

- Use exact RBAC action names from code (e.g., `view_insights` not "view insights")

- Reference permission system correctly (`template:view_insights` scope)

- Specify which roles have permissions by default

- Use full, correct paths (e.g., `/api/v2/insights/templates` not `/insights/templates`)

- Link to generated API documentation in `docs/reference/api/`

**CRITICAL**: All documentation pages must be added to `docs/manifest.json` to appear in navigation. Read the manifest file to understand the structure and find the appropriate section for your documentation. Place new pages in logical sections matching the existing hierarchy.

When documenting features that depend on upcoming PRs:

1. **Reference the PR explicitly** - Mention PR number and what it adds

2. **Document the feature anyway** - Write as if feature exists

3. **Link to auto-generated docs** - Point to CLI reference sections that will be created

4. **Update PR description** - Note documentation is included proactively

**Example**: Template Insights docs include `--disable-template-insights` flag from PR #20940 before it merged, with link to `../../reference/cli/server.md#--disable-template-insights` that will exist when the PR lands.

- **H3 subheadings** for each issue

- Format: Issue description followed by solution steps

- Bullet or numbered list

- Include version requirements, dependencies, permissions

- **Bold** (`**text**`): UI elements, important concepts, labels

- *Italic* (`*text*`): Rare, mainly for emphasis

- `Code` (`` `text` ``): Commands, file paths, parameter names

- Use for comparing options, listing parameters, showing permissions

- Left-align text, right-align numbers

- Keep simple - avoid nested formatting when possible

- **Always specify language**: `` ```sh ``, `` ```yaml ``, `` ```go ``

- Include comments for complex examples

- Keep minimal - show only relevant configuration

- **Comprehensive but scannable**: Cover all aspects but use clear headings

- **Break up long sections**: Use H3 subheadings for logical chunks

- **Visual hierarchy**: Images and code blocks break up text

Some content is auto-generated with comments:

<!-- Code generated by 'make docs/...' DO NOT EDIT -->

Don't manually edit auto-generated sections.

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

@.claude/docs/DOCS_STYLE_GUIDE.md