Skip to content

docs: address review comments for DOCS_STYLE_GUIDE.md #21178

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bpmct merged 2 commits into from
Dec 9, 2025
Merged

docs: address review comments for DOCS_STYLE_GUIDE.md #21178

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e1e14b2
docs: address review comments for DOCS_STYLE_GUIDE.md
bpmct Dec 9, 2025
8a0157d
fix: markdown linting errors in DOCS_STYLE_GUIDE.md
bpmct Dec 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 11 additions & 11 deletions .claude/docs/DOCS_STYLE_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ This guide documents documentation patterns observed in the Coder repository, ba

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.)
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.)
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
Expand Down Expand Up @@ -42,10 +42,7 @@ Template Insights provides detailed analytics and usage metrics for your Coder t

### Premium Feature Callout

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"]`
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"]`.

```markdown
# Template Insights (Premium)
Expand Down Expand Up @@ -94,7 +91,7 @@ When you have multiple screenshots showing different aspects of a feature:

### Screenshot Guidelines

**When screenshots are not available**: Use image placeholders with descriptive alt text and ask the user to provide screenshots:
**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:

```markdown
![Placeholder: Template Insights page showing weekly active users chart](../../images/admin/templates/template-insights.png)
Expand All @@ -103,6 +100,7 @@ When you have multiple screenshots showing different aspects of a feature:
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
Expand Down Expand Up @@ -133,7 +131,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 to present related but parallel documentation paths (e.g., different installation methods, platform-specific instructions)
- **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.

## Writing Style

Expand Down Expand Up @@ -162,19 +160,19 @@ Then ask: "Could you provide a screenshot of the Template Insights page? I've ad

### Command Examples

```markdown
````markdown
```sh
coder server --disable-template-insights
```
```
````

### Environment Variables

```markdown
````markdown
```sh
CODER_DISABLE_TEMPLATE_INSIGHTS=true
```
```
````

### Code Comments

Expand All @@ -191,6 +189,8 @@ 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
Expand Down
Loading