Skip to content

Commit 3ae0600

Browse files
bpmctclaude
bpmct
and
claude
authored
docs: add documentation style guide for AI agents (#21153)
Adds a comprehensive documentation style guide in `.claude/docs/DOCS_STYLE_GUIDE.md` documenting patterns observed across Coder's existing documentation. This guide is intended for AI agents to reference when writing documentation, ensuring consistency with project conventions. The guide covers research requirements (code verification, permissions model, UI thresholds), document structure (titles, premium callouts, overview sections), image usage (placement, captions, screenshot-driven organization), content organization, writing style, code examples, accuracy standards (specific numbers, permission actions, API endpoints), manifest requirements, and proactive documentation approaches. Placed in `.claude/docs/` alongside other agent-specific documentation (WORKFLOWS.md, ARCHITECTURE.md, etc.) and imported in CLAUDE.md to ensure it's automatically loaded into context for documentation work. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent 731683a commit 3ae0600

File tree

2 files changed

+310
-0
lines changed

2 files changed

+310
-0
lines changed

‎.claude/docs/DOCS_STYLE_GUIDE.md‎

Lines changed: 309 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,309 @@
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 10+ similar 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:
46+
47+
1. Add `(Premium)` suffix to the H1 heading - the documentation system automatically links these to premium pricing information
48+
2. Add premium badge in `manifest.json` with `"state": ["premium"]`
49+
50+
```markdown
51+
# Template Insights (Premium)
52+
```
53+
54+
### Overview Section Pattern
55+
56+
Common pattern after introduction:
57+
58+
```markdown
59+
## Overview
60+
61+
Template Insights offers visibility into:
62+
63+
- **Active Users**: Track the number of users actively using workspaces
64+
- **Application Usage**: See which applications users are accessing
65+
```
66+
67+
Use bold labels for capabilities, provides high-level understanding before details.
68+
69+
## Image Usage
70+
71+
### Placement and Format
72+
73+
**Place images after descriptive text**, then add caption:
74+
75+
```markdown
76+
![Template Insights page](../../images/admin/templates/template-insights.png)
77+
78+
<small>Template Insights showing weekly active users and connection latency metrics.</small>
79+
```
80+
81+
- Image format: `![Descriptive alt text](../../path/to/image.png)`
82+
- Caption: Use `<small>` tag below images
83+
- Alt text: Describe what's shown, not just repeat heading
84+
85+
### Image-Driven Documentation
86+
87+
When you have multiple screenshots showing different aspects of a feature:
88+
89+
1. **Structure sections around images** - Each major screenshot gets its own section
90+
2. **Describe what's visible** - Reference specific UI elements, data values shown in the screenshot
91+
3. **Flow naturally** - Let screenshots guide the reader through the feature
92+
93+
**Example**: Template Insights documentation has 3 screenshots that define the 3 main content sections.
94+
95+
### Screenshot Guidelines
96+
97+
**When screenshots are not available**: Use image placeholders with descriptive alt text and ask the user to provide screenshots:
98+
99+
```markdown
100+
![Placeholder: Template Insights page showing weekly active users chart](../../images/admin/templates/template-insights.png)
101+
```
102+
103+
Then ask: "Could you provide a screenshot of the Template Insights page? I've added a placeholder at [location]."
104+
105+
**When documenting with screenshots**:
106+
- Illustrate features being discussed in preceding text
107+
- Show actual UI/data, not abstract concepts
108+
- Reference specific values shown when explaining features
109+
- Organize documentation around key screenshots
110+
111+
## Content Organization
112+
113+
### Section Hierarchy
114+
115+
1. **H2 (##)**: Major sections - "Overview", "Accessing [Feature]", "Use Cases"
116+
2. **H3 (###)**: Subsections within major sections
117+
3. **H4 (####)**: Rare, only for deeply nested content
118+
119+
### Common Section Patterns
120+
121+
- **Accessing [Feature]**: How to navigate to/use the feature
122+
- **Use Cases**: Practical applications
123+
- **Permissions**: Access control information
124+
- **API Access**: Programmatic access details
125+
- **Related Documentation**: Links to related content
126+
127+
### Lists and Callouts
128+
129+
- **Unordered lists**: Non-sequential items, features, capabilities
130+
- **Ordered lists**: Step-by-step instructions
131+
- **Tables**: Comparing options, showing permissions, listing parameters
132+
- **Callouts**:
133+
- `> [!NOTE]` for additional information
134+
- `> [!WARNING]` for important warnings
135+
- `> [!TIP]` for helpful tips
136+
- **Tabs**: Use tabs to present related but parallel documentation paths (e.g., different installation methods, platform-specific instructions)
137+
138+
## Writing Style
139+
140+
### Tone and Voice
141+
142+
- **Direct and concise**: Avoid unnecessary words
143+
- **Active voice**: "Template Insights tracks users" not "Users are tracked"
144+
- **Present tense**: "The chart displays..." not "The chart will display..."
145+
- **Second person**: "You can view..." for instructions
146+
147+
### Terminology
148+
149+
- **Consistent terms**: Use same term throughout (e.g., "workspace" not "workspace environment")
150+
- **Bold for UI elements**: "Navigate to the **Templates** page"
151+
- **Code formatting**: Use backticks for commands, file paths, code
152+
- Inline: `` `coder server` ``
153+
- Blocks: Use triple backticks with language identifier
154+
155+
### Instructions
156+
157+
- **Numbered lists** for sequential steps
158+
- **Start with verb**: "Navigate to", "Click", "Select", "Run"
159+
- **Be specific**: Include exact button/menu names in bold
160+
161+
## Code Examples
162+
163+
### Command Examples
164+
165+
```markdown
166+
```sh
167+
coder server --disable-template-insights
168+
```
169+
```
170+
171+
### Environment Variables
172+
173+
```markdown
174+
```sh
175+
CODER_DISABLE_TEMPLATE_INSIGHTS=true
176+
```
177+
```
178+
179+
### Code Comments
180+
181+
- Keep minimal
182+
- Explain non-obvious parameters
183+
- Use `# Comment` for shell, `// Comment` for other languages
184+
185+
## Links and References
186+
187+
### Internal Links
188+
189+
Use relative paths from current file location:
190+
191+
- `[Template Permissions](./template-permissions.md)`
192+
- `[API documentation](../../reference/api/insights.md)`
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+
## Key Principles
304+
305+
1. **Research first** - Verify against actual code implementation
306+
2. **Be precise** - Use exact numbers, permission names, API paths
307+
3. **Visual structure** - Organize around screenshots when available
308+
4. **Link everything** - Related docs, API endpoints, CLI references
309+
5. **Manifest inclusion** - Add to manifest.json for navigation

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -197,6 +197,7 @@ clear what the new test covers.
197197
@.claude/docs/TESTING.md
198198
@.claude/docs/TROUBLESHOOTING.md
199199
@.claude/docs/DATABASE.md
200+
@.claude/docs/DOCS_STYLE_GUIDE.md
200201

201202
## Local Configuration
202203

0 commit comments

Comments
 (0)