1# Documentation Automation Agent Guidelines
2
3This file governs automated documentation updates triggered by code changes. All automation phases must comply with these rules.
4
5## Documentation System
6
7This documentation uses **mdBook** (https://rust-lang.github.io/mdBook/).
8
9### Key Files
10
11- **`docs/src/SUMMARY.md`**: Table of contents following mdBook format (https://rust-lang.github.io/mdBook/format/summary.html)
12- **`docs/book.toml`**: mdBook configuration
13- **`docs/.prettierrc`**: Prettier config (80 char line width)
14
15### SUMMARY.md Format
16
17The `SUMMARY.md` file defines the book structure. Format rules:
18
19- Chapter titles are links: `[Title](./path/to/file.md)`
20- Nesting via indentation (2 spaces per level)
21- Separators: `---` for horizontal rules between sections
22- Draft chapters: `[Title]()` (empty parens, not yet written)
23
24Example:
25
26```markdown
27# Section Title
28
29- [Chapter](./chapter.md)
30 - [Nested Chapter](./nested.md)
31
32---
33
34# Another Section
35```
36
37### Custom Preprocessor
38
39The docs use a custom preprocessor (`docs_preprocessor`) that expands special commands:
40
41| Syntax | Purpose | Example |
42| ----------------------------- | ------------------------------------- | ------------------------------- |
43| `{#kb action::ActionName}` | Keybinding for action | `{#kb agent::ToggleFocus}` |
44| `{#action agent::ActionName}` | Action reference (renders as command) | `{#action agent::OpenSettings}` |
45
46**Rules:**
47
48- Always use preprocessor syntax for keybindings instead of hardcoding
49- Action names use `snake_case` in the namespace, `PascalCase` for the action
50- Common namespaces: `agent::`, `editor::`, `assistant::`, `vim::`
51
52### Formatting Requirements
53
54All documentation must pass **Prettier** formatting:
55
56```sh
57cd docs && npx prettier --check src/
58```
59
60Before any documentation change is considered complete:
61
621. Run Prettier to format: `cd docs && npx prettier --write src/`
632. Verify it passes: `cd docs && npx prettier --check src/`
64
65Prettier config: 80 character line width (`docs/.prettierrc`)
66
67### Section Anchors
68
69Use `{#anchor-id}` syntax for linkable section headers:
70
71```markdown
72## Getting Started {#getting-started}
73
74### Custom Models {#anthropic-custom-models}
75```
76
77Anchor IDs should be:
78
79- Lowercase with hyphens
80- Unique within the page
81- Descriptive (can include parent context like `anthropic-custom-models`)
82
83### Code Block Annotations
84
85Use annotations after the language identifier to indicate file context:
86
87```markdown
88\`\`\`json [settings]
89{
90"agent": { ... }
91}
92\`\`\`
93
94\`\`\`json [keymap]
95[
96{ "bindings": { ... } }
97]
98\`\`\`
99```
100
101Valid annotations: `[settings]` (for settings.json), `[keymap]` (for keymap.json)
102
103### Blockquote Formatting
104
105Use bold labels for callouts:
106
107```markdown
108> **Note:** Important information the user should know.
109
110> **Tip:** Helpful advice that saves time or improves workflow.
111
112> **Warn:** Caution about potential issues or gotchas.
113```
114
115### Image References
116
117Images are hosted externally. Reference format:
118
119```markdown
120
121```
122
123### Cross-Linking
124
125- Relative links for same-directory: `[Agent Panel](./agent-panel.md)`
126- With anchors: `[Custom Models](./llm-providers.md#anthropic-custom-models)`
127- Parent directory: `[Telemetry](../telemetry.md)`
128
129## Voice and Tone
130
131### Core Principles
132
133- **Practical over promotional**: Focus on what users can do, not on selling Zed. Avoid marketing language like "powerful," "revolutionary," or "best-in-class."
134- **Honest about limitations**: When Zed lacks a feature or doesn't match another tool's depth, say so directly. Pair limitations with workarounds or alternative workflows.
135- **Direct and concise**: Use short sentences. Get to the point. Developers are scanning, not reading novels.
136- **Second person**: Address the reader as "you." Avoid "the user" or "one."
137- **Present tense**: "Zed opens the file" not "Zed will open the file."
138
139### What to Avoid
140
141- Superlatives without substance ("incredibly fast," "seamlessly integrated")
142- Hedging language ("simply," "just," "easily")—if something is simple, the instructions will show it
143- Apologetic tone for missing features—state the limitation and move on
144- Comparisons that disparage other tools—be factual, not competitive
145- Lots of use of em or en dashes.
146
147## Examples of Good Copy
148
149### Good: Direct and actionable
150
151```
152To format on save, open the Settings Editor (`Cmd+,`) and search for `format_on_save`. Set it to `on`.
153
154Or add this to your settings.json:
155{
156 "format_on_save": "on"
157}
158```
159
160### Bad: Wordy and promotional
161
162```
163Zed provides a powerful and seamless formatting experience. Simply navigate to the settings and you'll find the format_on_save option which enables Zed's incredible auto-formatting capabilities.
164```
165
166### Good: Honest about limitations
167
168```
169Zed doesn't index your project like IntelliJ does. You open a folder and start working immediately—no waiting. The trade-off: cross-project analysis relies on language servers, which may not go as deep.
170
171**How to adapt:**
172- Use `Cmd+Shift+F` for project-wide text search
173- Use `Cmd+O` for symbol search (powered by your language server)
174```
175
176### Bad: Defensive or dismissive
177
178```
179While some users might miss indexing, Zed's approach is actually better because it's faster.
180```
181
182## Scope
183
184### In-Scope Documentation
185
186- All Markdown files in `docs/src/`
187- `docs/src/SUMMARY.md` (mdBook table of contents)
188- Language-specific docs in `docs/src/languages/`
189- Feature docs (AI, extensions, configuration, etc.)
190
191### Out-of-Scope (Do Not Modify)
192
193- `CHANGELOG.md`, `CONTRIBUTING.md`, `README.md` at repo root
194- Inline code comments and rustdoc
195- `CLAUDE.md`, `GEMINI.md`, or other AI instruction files
196- Build configuration (`book.toml`, theme files, `docs_preprocessor`)
197- Any file outside `docs/src/`
198
199## Page Structure Patterns
200
201### Standard Page Layout
202
203Most documentation pages follow this structure:
204
2051. **Title** (H1) - Single sentence or phrase
2062. **Overview/Introduction** - 1-3 paragraphs explaining what this is
2073. **Getting Started** `{#getting-started}` - Prerequisites and first steps
2084. **Main Content** - Feature details, organized by topic
2095. **Advanced/Configuration** - Power user options
2106. **See Also** (optional) - Related documentation links
211
212### Settings Documentation Pattern
213
214When documenting settings:
215
2161. Show the Settings Editor (UI) approach first
2172. Then show JSON as "Or add this to your settings.json:"
2183. Always show complete, valid JSON with surrounding structure:
219
220```json [settings]
221{
222 "agent": {
223 "default_model": {
224 "provider": "anthropic",
225 "model": "claude-sonnet-4"
226 }
227 }
228}
229```
230
231### Provider/Feature Documentation Pattern
232
233For each provider or distinct feature:
234
2351. H3 heading with anchor: `### Provider Name {#provider-name}`
2362. Brief description (1-2 sentences)
2373. Setup steps (numbered list)
2384. Configuration example (JSON code block)
2395. Custom models section if applicable: `#### Custom Models {#provider-custom-models}`
240
241## Style Rules
242
243Inherit all conventions from `docs/.rules`. Key points:
244
245### Voice
246
247- Second person ("you"), present tense
248- Direct and concise—no hedging ("simply", "just", "easily")
249- Honest about limitations; no promotional language
250
251### Formatting
252
253- Keybindings: backticks with `+` for simultaneous keys (`Cmd+Shift+P`)
254- Show both macOS and Linux/Windows variants when they differ
255- Use `sh` code blocks for terminal commands
256- Settings: show Settings Editor UI first, JSON as secondary
257
258### Terminology
259
260| Use | Instead of |
261| --------------- | --------------------------------------------------------------------- |
262| folder | directory |
263| project | workspace |
264| Settings Editor | settings UI |
265| command palette | command bar |
266| panel | tool window, sidebar (be specific: "Project Panel," "Terminal Panel") |
267| language server | LSP (spell out first use, then LSP is fine) |
268
269## Zed-Specific Conventions
270
271### Recognized Rules Files
272
273When documenting rules/instructions for AI, note that Zed recognizes these files (in priority order):
274
275- `.rules`
276- `.cursorrules`
277- `.windsurfrules`
278- `.clinerules`
279- `.github/copilot-instructions.md`
280- `AGENT.md`
281- `AGENTS.md`
282- `CLAUDE.md`
283- `GEMINI.md`
284
285### Settings File Locations
286
287- macOS: `~/.config/zed/settings.json`
288- Linux: `~/.config/zed/settings.json`
289- Windows: `%AppData%\Zed\settings.json`
290
291### Keymap File Locations
292
293- macOS: `~/.config/zed/keymap.json`
294- Linux: `~/.config/zed/keymap.json`
295- Windows: `%AppData%\Zed\keymap.json`
296
297## Safety Constraints
298
299### Must Not
300
301- Delete existing documentation files
302- Remove sections documenting existing functionality
303- Change URLs or anchor links without verifying references
304- Modify `SUMMARY.md` structure without corresponding content
305- Add speculative documentation for unreleased features
306- Include internal implementation details not relevant to users
307
308### Must
309
310- Preserve existing structure when updating content
311- Maintain backward compatibility of documented settings/commands
312- Flag uncertainty explicitly rather than guessing
313- Link to related documentation when adding new sections
314
315## Change Classification
316
317### Requires Documentation Update
318
319- New user-facing features or commands
320- Changed keybindings or default behaviors
321- Modified settings schema or options
322- Deprecated or removed functionality
323- API changes affecting extensions
324
325### Does Not Require Documentation Update
326
327- Internal refactoring without behavioral changes
328- Performance optimizations (unless user-visible)
329- Bug fixes that restore documented behavior
330- Test changes
331- CI/CD changes
332
333## Output Format
334
335### Phase 4 Documentation Plan
336
337When generating a documentation plan, use this structure:
338
339```markdown
340## Documentation Impact Assessment
341
342### Summary
343
344Brief description of code changes analyzed.
345
346### Documentation Updates Required: [Yes/No]
347
348### Planned Changes
349
350#### 1. [File Path]
351
352- **Section**: [Section name or "New section"]
353- **Change Type**: [Update/Add/Deprecate]
354- **Reason**: Why this change is needed
355- **Description**: What will be added/modified
356
357#### 2. [File Path]
358
359...
360
361### Uncertainty Flags
362
363- [ ] [Description of any assumptions or areas needing confirmation]
364
365### No Changes Needed
366
367- [List files reviewed but not requiring updates, with brief reason]
368```
369
370### Phase 6 Summary Format
371
372```markdown
373## Documentation Update Summary
374
375### Changes Made
376
377| File | Change | Related Code |
378| -------------- | ----------------- | ----------------- |
379| path/to/doc.md | Brief description | link to PR/commit |
380
381### Rationale
382
383Brief explanation of why these updates were made.
384
385### Review Notes
386
387Any items reviewers should pay special attention to.
388```
389
390## Behavioral Guidelines
391
392### Conservative by Default
393
394- When uncertain whether to document something, flag it for human review
395- Prefer smaller, focused updates over broad rewrites
396- Do not "improve" documentation unrelated to the triggering code change
397
398### Traceability
399
400- Every documentation change should trace to a specific code change
401- Include references to relevant commits, PRs, or issues in summaries
402
403### Incremental Updates
404
405- Update existing sections rather than creating parallel documentation
406- Maintain consistency with surrounding content
407- Follow the established patterns in each documentation area