Skip to content

Commit c695a1f

Browse files
bpmctclaude
bpmct
and
claude
committed
docs: add documentation style guide for AI agents
Add comprehensive documentation style guide in .claude/docs/ directory following the format established in PR #21148 for PR_STYLE_GUIDE.md. This guide captures observed patterns from existing Coder documentation including: - Research requirements before writing (code verification, permissions, thresholds) - Document structure and organization patterns - Image usage and screenshot guidelines - Writing style and terminology conventions - Code examples and formatting standards - Documentation manifest requirements - Accuracy standards for specific numbers, permissions, and API endpoints - Proactive documentation approach for upcoming features 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent 82bb833 commit c695a1f

File tree

2 files changed

+296
-0
lines changed

2 files changed

+296
-0
lines changed

‎.claude/docs/DOCS_STYLE_GUIDE.md‎

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