1# Zed Documentation Guidelines
  2
  3## Voice and Tone
  4
  5### Core Principles
  6
  7- **Practical over promotional**: Focus on what users can do, not on selling Zed. Avoid marketing language like "powerful," "revolutionary," or "best-in-class."
  8- **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.
  9- **Direct and concise**: Use short sentences. Get to the point. Developers are scanning, not reading novels.
 10- **Second person**: Address the reader as "you." Avoid "the user" or "one."
 11- **Present tense**: "Zed opens the file" not "Zed will open the file."
 12
 13### What to Avoid
 14
 15- Superlatives without substance ("incredibly fast," "seamlessly integrated")
 16- Hedging language ("simply," "just," "easily")—if something is simple, the instructions will show it
 17- Apologetic tone for missing features—state the limitation and move on
 18- Comparisons that disparage other tools—be factual, not competitive
 19- Meta-commentary about honesty ("the honest take is...", "to be frank...", "honestly...")—let honesty show through frank assessments, not announcements
 20- LLM-isms and filler words ("entirely," "certainly,", "deeply," "definitely," "actually")—these add nothing
 21
 22## Content Structure
 23
 24### Page Organization
 25
 261. **Start with the goal**: Open with what the reader will accomplish, not background
 272. **Front-load the action**: Put the most common task first, edge cases later
 283. **Use headers liberally**: Readers scan; headers help them find what they need
 294. **End with "what's next"**: Link to related docs or logical next steps
 30
 31### Section Patterns
 32
 33For how-to content:
 341. Brief context (1-2 sentences max)
 352. Steps or instructions
 363. Example (code block or screenshot reference)
 374. Tips or gotchas (if any)
 38
 39For reference content:
 401. What it is (definition)
 412. How to access/configure it
 423. Options/parameters table
 434. Examples
 44
 45## Formatting Conventions
 46
 47### Keybindings
 48
 49- Use backticks for key combinations: `Cmd+Shift+P`
 50- Show both macOS and Linux/Windows when they differ: `Cmd+,` (macOS) or `Ctrl+,` (Linux/Windows)
 51- Use `+` to join simultaneous keys, space for sequences: `Cmd+K Cmd+C`
 52
 53### Code and Settings
 54
 55- Inline code for setting names, file paths, commands: `format_on_save`, `.zed/settings.json`, `zed .`
 56- Code blocks for JSON config, multi-line commands, or file contents
 57- Always show complete, working examples—not fragments
 58
 59### Terminal Commands
 60
 61Use `sh` code blocks for terminal commands, not plain backticks:
 62
 63```sh
 64brew install zed-editor/zed/zed
 65```
 66
 67Not:
 68```
 69brew install zed-editor/zed/zed
 70```
 71
 72For single inline commands in prose, backticks are fine: `zed .`
 73
 74### Tables
 75
 76Use tables for:
 77- Keybinding comparisons between editors
 78- Settings mappings (e.g., VS Code → Zed)
 79- Feature comparisons with clear columns
 80
 81Format:
 82```
 83| Action | Shortcut | Notes |
 84| --- | --- | --- |
 85| Open File | `Cmd+O` | Works from any context |
 86```
 87
 88### Tips and Notes
 89
 90Use blockquote format with bold label:
 91```
 92> **Tip:** Practical advice that helps bridge gaps or saves time.
 93```
 94
 95Reserve tips for genuinely useful information, not padding.
 96
 97## Writing Guidelines
 98
 99### Settings Documentation
100
101- **Settings Editor first**: Show how to find and change settings in the UI before showing JSON
102- **JSON as secondary**: Present JSON examples as "Or add this to your settings.json" for users who prefer direct editing
103- **Complete examples**: Include the full JSON structure, not just the value
104
105### Migration Guides
106
107- **Jobs to be done**: Frame around tasks ("How do I search files?") not features ("File Search Feature")
108- **Acknowledge the source**: Respect that users have muscle memory and preferences from their previous editor
109- **Keybindings tables**: Essential for migration docs—show what maps, what's different, what's missing
110- **Trade-offs section**: Be explicit about what the user gains and loses in the switch
111
112### Feature Documentation
113
114- **Start with the default**: Document the out-of-box experience first
115- **Configuration options**: Group related settings together
116- **Cross-link generously**: Link to related features, settings reference, and relevant guides
117
118## Terminology
119
120| Use | Instead of |
121| --- | --- |
122| folder | directory (in user-facing text) |
123| project | workspace (Zed doesn't have workspaces) |
124| Settings Editor | settings UI, preferences |
125| command palette | command bar, action search |
126| language server | LSP (spell out first use, then LSP is fine) |
127| panel | tool window, sidebar (be specific: "Project Panel," "Terminal Panel") |
128
129## Examples
130
131### Good: Direct and actionable
132```
133To format on save, open the Settings Editor (`Cmd+,`) and search for `format_on_save`. Set it to `on`.
134
135Or add this to your settings.json:
136{
137  "format_on_save": "on"
138}
139```
140
141### Bad: Wordy and promotional
142```
143Zed 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.
144```
145
146### Good: Honest about limitations
147```
148Zed 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.
149
150**How to adapt:**
151- Use `Cmd+Shift+F` for project-wide text search
152- Use `Cmd+O` for symbol search (powered by your language server)
153```
154
155### Bad: Defensive or dismissive
156```
157While some users might miss indexing, Zed's approach is actually better because it's faster.
158```