Skip to content

Commit 4c49d23

Browse files
jakehwlljakehwll
authored
Merge branch 'main' into jakehwll/requestlogsrow-cached-tokens
2 parents 52656f1 + 96fca01 commit 4c49d23

File tree

291 files changed

+9429
-3302
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

291 files changed

+9429
-3302
lines changed

‎.claude/docs/DOCS_STYLE_GUIDE.md‎

Lines changed: 321 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,321 @@
1+
# Documentation Style Guide
2+
3+
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.
4+
5+
## Research Before Writing
6+
7+
Before documenting a feature:
8+
9+
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.)
10+
2. **Read the code implementation** - Check backend endpoints, frontend components, database queries
11+
3. **Verify permissions model** - Look up RBAC actions in `coderd/rbac/` (e.g., `view_insights` for Template Insights)
12+
4. **Check UI thresholds and defaults** - Review frontend code for color thresholds, time intervals, display logic
13+
5. **Cross-reference with tests** - Test files document expected behavior and edge cases
14+
6. **Verify API endpoints** - Check `coderd/coderd.go` for route registration
15+
16+
### Code Verification Checklist
17+
18+
When documenting features, always verify these implementation details:
19+
20+
- Read handler implementation in `coderd/`
21+
- Check permission requirements in `coderd/rbac/`
22+
- Review frontend components in `site/src/pages/` or `site/src/modules/`
23+
- Verify display thresholds and intervals (e.g., color codes, time defaults)
24+
- Confirm API endpoint paths and parameters
25+
- Check for server flags in serpent configuration
26+
27+
## Document Structure
28+
29+
### Title and Introduction Pattern
30+
31+
**H1 heading**: Single clear title without prefix
32+
33+
```markdown
34+
# Template Insights
35+
```
36+
37+
**Introduction**: 1-2 sentences describing what the feature does, concise and actionable
38+
39+
```markdown
40+
Template Insights provides detailed analytics and usage metrics for your Coder templates.
41+
```
42+
43+
### Premium Feature Callout
44+
45+
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"]`.
46+
47+
```markdown
48+
# Template Insights (Premium)
49+
```
50+
51+
### Overview Section Pattern
52+
53+
Common pattern after introduction:
54+
55+
```markdown
56+
## Overview
57+
58+
Template Insights offers visibility into:
59+
60+
- **Active Users**: Track the number of users actively using workspaces
61+
- **Application Usage**: See which applications users are accessing
62+
```
63+
64+
Use bold labels for capabilities, provides high-level understanding before details.
65+
66+
## Image Usage
67+
68+
### Placement and Format
69+
70+
**Place images after descriptive text**, then add caption:
71+
72+
```markdown
73+
![Template Insights page](../../images/admin/templates/template-insights.png)
74+
75+
<small>Template Insights showing weekly active users and connection latency metrics.</small>
76+
```
77+
78+
- Image format: `![Descriptive alt text](../../path/to/image.png)`
79+
- Caption: Use `<small>` tag below images
80+
- Alt text: Describe what's shown, not just repeat heading
81+
82+
### Image-Driven Documentation
83+
84+
When you have multiple screenshots showing different aspects of a feature:
85+
86+
1. **Structure sections around images** - Each major screenshot gets its own section
87+
2. **Describe what's visible** - Reference specific UI elements, data values shown in the screenshot
88+
3. **Flow naturally** - Let screenshots guide the reader through the feature
89+
90+
**Example**: Template Insights documentation has 3 screenshots that define the 3 main content sections.
91+
92+
### Screenshot Guidelines
93+
94+
**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:
95+
96+
```markdown
97+
![Placeholder: Template Insights page showing weekly active users chart](../../images/admin/templates/template-insights.png)
98+
```
99+
100+
Then ask: "Could you provide a screenshot of the Template Insights page? I've added a placeholder at [location]."
101+
102+
**When documenting with screenshots**:
103+
104+
- Illustrate features being discussed in preceding text
105+
- Show actual UI/data, not abstract concepts
106+
- Reference specific values shown when explaining features
107+
- Organize documentation around key screenshots
108+
109+
## Content Organization
110+
111+
### Section Hierarchy
112+
113+
1. **H2 (##)**: Major sections - "Overview", "Accessing [Feature]", "Use Cases"
114+
2. **H3 (###)**: Subsections within major sections
115+
3. **H4 (####)**: Rare, only for deeply nested content
116+
117+
### Common Section Patterns
118+
119+
- **Accessing [Feature]**: How to navigate to/use the feature
120+
- **Use Cases**: Practical applications
121+
- **Permissions**: Access control information
122+
- **API Access**: Programmatic access details
123+
- **Related Documentation**: Links to related content
124+
125+
### Lists and Callouts
126+
127+
- **Unordered lists**: Non-sequential items, features, capabilities
128+
- **Ordered lists**: Step-by-step instructions
129+
- **Tables**: Comparing options, showing permissions, listing parameters
130+
- **Callouts**:
131+
- `> [!NOTE]` for additional information
132+
- `> [!WARNING]` for important warnings
133+
- `> [!TIP]` for helpful tips
134+
- **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.
135+
136+
## Writing Style
137+
138+
### Tone and Voice
139+
140+
- **Direct and concise**: Avoid unnecessary words
141+
- **Active voice**: "Template Insights tracks users" not "Users are tracked"
142+
- **Present tense**: "The chart displays..." not "The chart will display..."
143+
- **Second person**: "You can view..." for instructions
144+
145+
### Terminology
146+
147+
- **Consistent terms**: Use same term throughout (e.g., "workspace" not "workspace environment")
148+
- **Bold for UI elements**: "Navigate to the **Templates** page"
149+
- **Code formatting**: Use backticks for commands, file paths, code
150+
- Inline: `` `coder server` ``
151+
- Blocks: Use triple backticks with language identifier
152+
153+
### Instructions
154+
155+
- **Numbered lists** for sequential steps
156+
- **Start with verb**: "Navigate to", "Click", "Select", "Run"
157+
- **Be specific**: Include exact button/menu names in bold
158+
159+
## Code Examples
160+
161+
### Command Examples
162+
163+
````markdown
164+
```sh
165+
coder server --disable-template-insights
166+
```
167+
````
168+
169+
### Environment Variables
170+
171+
````markdown
172+
```sh
173+
CODER_DISABLE_TEMPLATE_INSIGHTS=true
174+
```
175+
````
176+
177+
### Code Comments
178+
179+
- Keep minimal
180+
- Explain non-obvious parameters
181+
- Use `# Comment` for shell, `// Comment` for other languages
182+
183+
## Links and References
184+
185+
### Internal Links
186+
187+
Use relative paths from current file location:
188+
189+
- `[Template Permissions](./template-permissions.md)`
190+
- `[API documentation](../../reference/api/insights.md)`
191+
192+
For cross-linking to Coder registry templates or other external Coder resources, reference the appropriate registry URLs.
193+
194+
### Cross-References
195+
196+
- Link to related documentation at the end
197+
- Use descriptive text: "Learn about [template access control](./template-permissions.md)"
198+
- Not just: "[Click here](./template-permissions.md)"
199+
200+
### API References
201+
202+
Link to specific endpoints:
203+
204+
```markdown
205+
- `/api/v2/insights/templates` - Template usage metrics
206+
```
207+
208+
## Accuracy Standards
209+
210+
### Specific Numbers Matter
211+
212+
Document exact values from code:
213+
214+
- **Thresholds**: "green < 150ms, yellow 150-300ms, red ≥300ms"
215+
- **Time intervals**: "daily for templates < 5 weeks old, weekly for 5+ weeks"
216+
- **Counts and limits**: Use precise numbers, not approximations
217+
218+
### Permission Actions
219+
220+
- Use exact RBAC action names from code (e.g., `view_insights` not "view insights")
221+
- Reference permission system correctly (`template:view_insights` scope)
222+
- Specify which roles have permissions by default
223+
224+
### API Endpoints
225+
226+
- Use full, correct paths (e.g., `/api/v2/insights/templates` not `/insights/templates`)
227+
- Link to generated API documentation in `docs/reference/api/`
228+
229+
## Documentation Manifest
230+
231+
**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.
232+
233+
## Proactive Documentation
234+
235+
When documenting features that depend on upcoming PRs:
236+
237+
1. **Reference the PR explicitly** - Mention PR number and what it adds
238+
2. **Document the feature anyway** - Write as if feature exists
239+
3. **Link to auto-generated docs** - Point to CLI reference sections that will be created
240+
4. **Update PR description** - Note documentation is included proactively
241+
242+
**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.
243+
244+
## Special Sections
245+
246+
### Troubleshooting
247+
248+
- **H3 subheadings** for each issue
249+
- Format: Issue description followed by solution steps
250+
251+
### Prerequisites
252+
253+
- Bullet or numbered list
254+
- Include version requirements, dependencies, permissions
255+
256+
## Formatting and Linting
257+
258+
**Always run these commands before submitting documentation:**
259+
260+
```sh
261+
make fmt/markdown # Format markdown tables and content
262+
make lint/markdown # Lint and fix markdown issues
263+
```
264+
265+
These ensure consistent formatting and catch common documentation errors.
266+
267+
## Formatting Conventions
268+
269+
### Text Formatting
270+
271+
- **Bold** (`**text**`): UI elements, important concepts, labels
272+
- *Italic* (`*text*`): Rare, mainly for emphasis
273+
- `Code` (`` `text` ``): Commands, file paths, parameter names
274+
275+
### Tables
276+
277+
- Use for comparing options, listing parameters, showing permissions
278+
- Left-align text, right-align numbers
279+
- Keep simple - avoid nested formatting when possible
280+
281+
### Code Blocks
282+
283+
- **Always specify language**: `` ```sh ``, `` ```yaml ``, `` ```go ``
284+
- Include comments for complex examples
285+
- Keep minimal - show only relevant configuration
286+
287+
## Document Length
288+
289+
- **Comprehensive but scannable**: Cover all aspects but use clear headings
290+
- **Break up long sections**: Use H3 subheadings for logical chunks
291+
- **Visual hierarchy**: Images and code blocks break up text
292+
293+
## Auto-Generated Content
294+
295+
Some content is auto-generated with comments:
296+
297+
```markdown
298+
<!-- Code generated by 'make docs/...' DO NOT EDIT -->
299+
```
300+
301+
Don't manually edit auto-generated sections.
302+
303+
## URL Redirects
304+
305+
When renaming or moving documentation pages, redirects must be added to prevent broken links.
306+
307+
**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:
308+
309+
- **Redirect configuration**: https://github.com/coder/coder.com/blob/master/redirects.json
310+
- **Do NOT create** a `docs/_redirects` file - this format (used by Netlify/Cloudflare Pages) is not processed by coder.com
311+
312+
When you rename or move a doc page, create a PR in coder/coder.com to add the redirect.
313+
314+
## Key Principles
315+
316+
1. **Research first** - Verify against actual code implementation
317+
2. **Be precise** - Use exact numbers, permission names, API paths
318+
3. **Visual structure** - Organize around screenshots when available
319+
4. **Link everything** - Related docs, API endpoints, CLI references
320+
5. **Manifest inclusion** - Add to manifest.json for navigation
321+
6. **Add redirects** - When moving/renaming pages, add redirects in coder/coder.com repo

0 commit comments

Comments
 (0)