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
 21## Content Structure
 22
 23### Page Organization
 24
 251. **Start with the goal**: Open with what the reader will accomplish, not background
 262. **Front-load the action**: Put the most common task first, edge cases later
 273. **Use headers liberally**: Readers scan; headers help them find what they need
 284. **End with "what's next"**: Link to related docs or logical next steps
 29
 30### Section Patterns
 31
 32For how-to content:
 331. Brief context (1-2 sentences max)
 342. Steps or instructions
 353. Example (code block or screenshot reference)
 364. Tips or gotchas (if any)
 37
 38For reference content:
 391. What it is (definition)
 402. How to access/configure it
 413. Options/parameters table
 424. Examples
 43
 44## Formatting Conventions
 45
 46### Keybindings
 47
 48- Use backticks for key combinations: `Cmd+Shift+P`
 49- Show both macOS and Linux/Windows when they differ: `Cmd+,` (macOS) or `Ctrl+,` (Linux/Windows)
 50- Use `+` to join simultaneous keys, space for sequences: `Cmd+K Cmd+C`
 51
 52### Code and Settings
 53
 54- Inline code for setting names, file paths, commands: `format_on_save`, `.zed/settings.json`, `zed .`
 55- Code blocks for JSON config, multi-line commands, or file contents
 56- Always show complete, working examples—not fragments
 57
 58### Terminal Commands
 59
 60Use `sh` code blocks for terminal commands, not plain backticks:
 61
 62```sh
 63brew install zed-editor/zed/zed
 64```
 65
 66Not:
 67```
 68brew install zed-editor/zed/zed
 69```
 70
 71For single inline commands in prose, backticks are fine: `zed .`
 72
 73### Tables
 74
 75Use tables for:
 76- Keybinding comparisons between editors
 77- Settings mappings (e.g., VS Code → Zed)
 78- Feature comparisons with clear columns
 79
 80Format:
 81```
 82| Action | Shortcut | Notes |
 83| --- | --- | --- |
 84| Open File | `Cmd+O` | Works from any context |
 85```
 86
 87### Tips and Notes
 88
 89Use blockquote format with bold label:
 90```
 91> **Tip:** Practical advice that helps bridge gaps or saves time.
 92```
 93
 94Reserve tips for genuinely useful information, not padding.
 95
 96## Writing Guidelines
 97
 98### Settings Documentation
 99
100- **Settings Editor first**: Show how to find and change settings in the UI before showing JSON
101- **JSON as secondary**: Present JSON examples as "Or add this to your settings.json" for users who prefer direct editing
102- **Complete examples**: Include the full JSON structure, not just the value
103
104### Migration Guides
105
106- **Jobs to be done**: Frame around tasks ("How do I search files?") not features ("File Search Feature")
107- **Acknowledge the source**: Respect that users have muscle memory and preferences from their previous editor
108- **Keybindings tables**: Essential for migration docs—show what maps, what's different, what's missing
109- **Trade-offs section**: Be explicit about what the user gains and loses in the switch
110
111### Feature Documentation
112
113- **Start with the default**: Document the out-of-box experience first
114- **Configuration options**: Group related settings together
115- **Cross-link generously**: Link to related features, settings reference, and relevant guides
116
117## Terminology
118
119| Use | Instead of |
120| --- | --- |
121| folder | directory (in user-facing text) |
122| project | workspace (Zed doesn't have workspaces) |
123| Settings Editor | settings UI, preferences |
124| command palette | command bar, action search |
125| language server | LSP (spell out first use, then LSP is fine) |
126| panel | tool window, sidebar (be specific: "Project Panel," "Terminal Panel") |
127
128## Examples
129
130### Good: Direct and actionable
131```
132To format on save, open the Settings Editor (`Cmd+,`) and search for `format_on_save`. Set it to `on`.
133
134Or add this to your settings.json:
135{
136  "format_on_save": "on"
137}
138```
139
140### Bad: Wordy and promotional
141```
142Zed 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.
143```
144
145### Good: Honest about limitations
146```
147Zed 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.
148
149**How to adapt:**
150- Use `Cmd+Shift+F` for project-wide text search
151- Use `Cmd+O` for symbol search (powered by your language server)
152```
153
154### Bad: Defensive or dismissive
155```
156While some users might miss indexing, Zed's approach is actually better because it's faster.
157```