@@ -126,6 +126,59 @@ Images are hosted externally. Reference format:
- With anchors: `[Custom Models](./llm-providers.md#anthropic-custom-models)`
- Parent directory: `[Telemetry](../telemetry.md)`
+## Voice and Tone
+
+### Core Principles
+
+- **Practical over promotional**: Focus on what users can do, not on selling Zed. Avoid marketing language like "powerful," "revolutionary," or "best-in-class."
+- **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.
+- **Direct and concise**: Use short sentences. Get to the point. Developers are scanning, not reading novels.
+- **Second person**: Address the reader as "you." Avoid "the user" or "one."
+- **Present tense**: "Zed opens the file" not "Zed will open the file."
+
+### What to Avoid
+
+- Superlatives without substance ("incredibly fast," "seamlessly integrated")
+- Hedging language ("simply," "just," "easily")—if something is simple, the instructions will show it
+- Apologetic tone for missing features—state the limitation and move on
+- Comparisons that disparage other tools—be factual, not competitive
+- Lots of use of em or en dashes.
+
+## Examples of Good Copy
+
+### Good: Direct and actionable
+
+```
+To format on save, open the Settings Editor (`Cmd+,`) and search for `format_on_save`. Set it to `on`.
+
+Or add this to your settings.json:
+{
+ "format_on_save": "on"
+}
+```
+
+### Bad: Wordy and promotional
+
+```
+Zed 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.
+```
+
+### Good: Honest about limitations
+
+```
+Zed 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.
+
+**How to adapt:**
+- Use `Cmd+Shift+F` for project-wide text search
+- Use `Cmd+O` for symbol search (powered by your language server)
+```
+
+### Bad: Defensive or dismissive
+
+```
+While some users might miss indexing, Zed's approach is actually better because it's faster.
+```
+
## Scope
### In-Scope Documentation
@@ -204,13 +257,14 @@ Inherit all conventions from `docs/.rules`. Key points:
### Terminology
-| Use | Instead of |
-| --------------- | -------------------------------------- |
-| folder | directory |
-| project | workspace |
-| Settings Editor | settings UI |
-| command palette | command bar |
-| panel | sidebar (be specific: "Project Panel") |
+| Use | Instead of |
+| --------------- | --------------------------------------------------------------------- |
+| folder | directory |
+| project | workspace |
+| Settings Editor | settings UI |
+| command palette | command bar |
+| panel | tool window, sidebar (be specific: "Project Panel," "Terminal Panel") |
+| language server | LSP (spell out first use, then LSP is fine) |
## Zed-Specific Conventions