1# Proposed Zed Documentation Information Architecture
2
3This document outlines a proposed restructuring of Zed's documentation to improve discoverability, separate task-oriented content from reference material, and better serve users with different goals (new users, migrating users, power users).
4
5---
6
7## Proposed IA Structure
8
9```markdown
10# Get Started
11
12- Welcome # Hub page with job-to-be-done cards
13- Installation
14- Your First 10 Minutes in Zed # True quickstart: open project → write code → use AI → run
15- Key Concepts # Mental models: workspaces, buffers, panels, command palette
16
17# Quickstarts # Task-focused, 5-10 min each
18
19- Set Up AI in Zed
20- Work on a Remote Server
21- Configure Your Language
22- Customize Zed to Feel Like Home
23
24# Coming From... # Migration guides
25
26- VS Code
27- Vim / Neovim
28- JetBrains
29- Cursor
30
31# AI # Key differentiator - prominent placement
32
33- Overview
34- Agent Panel
35 - Tools
36 - External Agents
37- Inline Assistant
38- Edit Prediction
39- Text Threads
40- Rules
41- Model Context Protocol
42- Configuration
43 - LLM Providers
44 - Agent Settings
45- Subscription
46 - Billing
47 - Models
48 - Plans and Usage
49
50# Working with Code # Daily workflow, organized by job
51
52- Overview # Walkthrough: open → edit → navigate → run → commit
53- Editing Code
54 - Code Completions
55 - Snippets
56 - Formatting & Linting
57 - Diagnostics & Quick Fixes
58 - Multibuffers
59- Finding & Navigating
60 - Command Palette
61 - File Finder & Project Search
62 - Go to Definition & Symbol Search
63 - Outline Panel
64- Running & Testing
65 - Tasks
66 - Terminal
67 - Debugger
68 - REPL
69- Git
70
71# Collaboration
72
73- Overview
74- Channels
75- Private Calls
76
77# Remote Development
78
79- Overview
80- SSH Connections
81- Dev Containers
82
83# Languages
84
85- Overview # Hub with capability tags (LSP, Debug, Format, etc.)
86- Configuring Languages
87 - Toolchains
88- Popular Languages # Curated, workflow-focused
89 - Python
90 - JavaScript / TypeScript
91 - Rust
92 - Go
93 - C / C++
94- All Languages # Searchable/filterable reference
95
96# Customization # Personalization, organized by goal
97
98- Overview # "Customize in 5 minutes" + how settings work
99- Appearance
100 - Themes
101 - Icon Themes
102 - Fonts & Visual Tweaks
103- Keybindings
104 - Custom Key Bindings
105 - Vim Mode
106 - Helix Mode
107- Snippets
108
109# Extensions
110
111- Overview
112- Installing Extensions
113- Developing Extensions
114- Extension Capabilities
115- Extension Types
116 - Language Extensions
117 - Theme Extensions
118 - Icon Theme Extensions
119 - Debugger Extensions
120 - Slash Command Extensions
121 - Agent Server Extensions
122 - MCP Server Extensions
123
124# Reference # Lookup-only, not for reading
125
126- All Settings
127- All Actions
128- Default Key Bindings
129- CLI Reference
130- Environment Variables
131- Glob Patterns
132
133# Platform Support
134
135- macOS
136- Windows
137- Linux
138
139# Account & Privacy
140
141- Sign In
142- Privacy and Security
143- Telemetry
144
145# Troubleshooting
146
147- Common Issues
148- Performance
149- Update
150- Uninstall
151
152# Developing Zed
153
154- Contributing
155- Building from Source
156 - macOS
157 - Linux
158 - Windows
159 - FreeBSD
160- Local Collaboration
161- Using Debuggers
162- Glossary
163- Release Notes
164```
165
166---
167
168## Deep Dive: Working with Code
169
170This section replaces the current "Using Zed" catch-all. Instead of listing features, it's organized around **what users are trying to accomplish** in their daily workflow.
171
172### Design Principles
173
1741. **Overview as workflow guide**: The overview page walks through a typical session (open project → write code → find things → run/test → commit), linking to detailed pages
1752. **Group by job, not feature**: "Finding & Navigating" groups file finder, symbol search, go-to-definition, and outline because they all serve the job of "I need to find something"
1763. **Progressive disclosure**: Start with the common case, link to advanced topics
177
178### Proposed Structure
179
180**Working with Code**
181
182```
183Overview
184├── "A day in Zed" walkthrough
185├── Links to each sub-section
186└── Quick tips for common tasks
187
188Editing Code
189├── Code Completions (LSP, AI-powered, snippets integration)
190├── Snippets (creating, using, language-specific)
191├── Formatting & Linting (format on save, linter integration)
192├── Diagnostics & Quick Fixes (error navigation, code actions)
193└── Multibuffers (what they are, when to use them)
194
195Finding & Navigating
196├── Command Palette (the hub for everything)
197├── File Finder & Project Search (fuzzy find, ripgrep, filters)
198├── Go to Definition & Symbol Search (LSP navigation, workspace symbols)
199└── Outline Panel (file structure, breadcrumbs)
200
201Running & Testing
202├── Tasks (defining, running, task templates)
203├── Terminal (integrated terminal, shell integration)
204├── Debugger (breakpoints, stepping, variables, DAP)
205└── REPL (interactive development, Jupyter-style)
206
207Git
208├── Staging & committing
209├── Branches
210├── Diff view
211├── Blame & history
212└── (future: GitHub integration)
213
214```
215
216### What This Replaces
217
218| Current "Using Zed" Item | New Location |
219| ------------------------ | ---------------------------------------- |
220| Multibuffers | Working with Code → Editing Code |
221| Command Palette | Working with Code → Finding & Navigating |
222| Command-line Interface | Reference → CLI Reference |
223| Outline Panel | Working with Code → Finding & Navigating |
224| Code Completions | Working with Code → Editing Code |
225| Collaboration | Collaboration (top-level section) |
226| Git | Working with Code → Git |
227| Debugger | Working with Code → Running & Testing |
228| Diagnostics | Working with Code → Editing Code |
229| Tasks | Working with Code → Running & Testing |
230| Remote Development | Remote Development (top-level section) |
231| Dev Containers | Remote Development |
232| Environment Variables | Reference |
233| REPL | Working with Code → Running & Testing |
234
235---
236
237## Deep Dive: Customization
238
239This section replaces "Configuration" and reframes it around **user goals** rather than settings categories.
240
241### Design Principles
242
2431. **Start with outcomes**: Users don't want to "configure settings" — they want Zed to look and feel a certain way
2442. **Quick wins first**: Overview page shows how to customize the essentials in 5 minutes
2453. **Explain the system**: Help users understand how settings work (JSON, project vs global, settings UI, deep links)
2464. **Separate appearance from behavior**: Visual customization is different from keybinding customization
247
248### Proposed Structure
249
250**Customization**
251
252```
253Overview
254├── "Customize Zed in 5 minutes" quick guide
255├── How settings work (JSON, project vs global, settings UI)
256├── Using settings deep links
257└── Links to detailed sections
258
259Appearance
260├── Themes (installing, switching, creating)
261├── Icon Themes
262├── Fonts & Visual Tweaks (UI density, status bar, tab bar, etc.)
263
264Keybindings
265├── Custom Key Bindings (understanding the keymap, common customizations)
266├── Vim Mode (setup, differences from native vim, customization)
267├── Helix Mode (setup, key differences)
268
269Snippets
270├── Using snippets
271├── Creating custom snippets
272├── Language-specific snippets
273
274```
275
276### What This Replaces
277
278| Current "Configuration" Item | New Location |
279| ---------------------------- | --------------------------------- |
280| Configuring Zed | Reference → All Settings |
281| Configuring Languages | Languages → Configuring Languages |
282| Key bindings | Customization→ Keybindings |
283| All Actions | Reference → All Actions |
284| Snippets | Customization→ Snippets |
285| Themes | Customization→ Appearance |
286| Icon Themes | Customization→ Appearance |
287| Visual Customization | Customization→ Appearance |
288| Vim Mode | Customization→ Keybindings |
289| Helix Mode | Customization→ Keybindings |
290
291### Key Insight: Settings Reference vs. Customization Guide
292
293The current `configuring-zed.md` is a **reference** (lookup all 200+ settings). That belongs in the Reference section.
294
295"Making Zed Yours" is a **guide** that helps users accomplish goals:
296
297- "I want Zed to look like my old editor" → Themes, fonts
298- "I want to use my vim muscle memory" → Vim Mode
299- "I want to change what ⌘+P does" → Custom Key Bindings
300
301The guide pages should link to the reference when users need to look up specific settings.
302
303---
304
305## Summary of Changes
306
307| Current | Proposed | Rationale |
308| ------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------ |
309| Getting Started (5 items) | Get Started (4) + Quickstarts (4) + Coming From... (4) | Split welcome/install from task-focused quickstarts and migration guides |
310| Configuration (9 items, front-loaded) | Customization(goal-oriented) + Reference | Users want outcomes, not settings; reference is for lookup |
311| Using Zed (14 items, catch-all) | Working with Code (job-organized) + Collaboration + Remote Dev | Group by workflow: editing, navigating, running, git |
312| AI (section 5) | AI (section 4) | Promote key differentiator |
313| Language Support (60+ flat list) | Languages with Popular grouping + filterable All Languages | Reduce cognitive load, highlight common languages |
314| No Reference section | Reference (6 items) | Explicitly label lookup-only content |
315| Troubleshooting in Getting Started | Troubleshooting as dedicated section | Easier to find when users need help |
316
317---
318
319## Content Gaps: New Pages Needed
320
321### Get Started & Quickstarts
322
323- `welcome.md` - Hub page with job-to-be-done cards
324- `first-10-minutes.md` - True quickstart walkthrough
325- `concepts.md` - Mental models for Zed
326- `quickstarts/ai-setup.md`
327- `quickstarts/remote-dev.md`
328- `quickstarts/language-setup.md`
329- `quickstarts/customize.md`
330
331### Migration Guides
332
333- `migration/vscode.md` ✅
334- `migration/vim.md`
335- `migration/jetbrains.md`
336- `migration/cursor.md`
337
338### Working with Code
339
340- `working-with-code/overview.md` - "A day in Zed" walkthrough
341- `working-with-code/editing/formatting-linting.md`
342- `working-with-code/navigating/file-finder.md`
343- `working-with-code/navigating/symbols.md`
344
345### Customization
346
347- `customization/overview.md` - "Customize in 5 minutes" + how settings work
348- `customization/appearance/fonts-visual.md`
349
350### Platform Support
351
352- `platforms/macos.md` (currently missing)
353
354### Reference
355
356- `reference/default-keybindings.md`
357
358---
359
360## Pages to Rework
361
362| Page | Changes Needed |
363| -------------------- | ---------------------------------------------------------- |
364| `configuring-zed.md` | Relabel as "All Settings" reference, add on-page filtering |
365| `all-actions.md` | Add filtering by category (Agent, Editor, Git, etc.) |
366| `languages.md` | Transform into filterable hub with capability tags |
367| `quick-start.md` | Rewrite as true 5-10 minute walkthrough |
368
369---
370
371## Doc Types
372
373Each page should be labeled with a type for clarity:
374
375| Type | Purpose | Example |
376| -------------- | ---------------------------- | ------------------ |
377| **Quickstart** | 5-10 min, end-to-end task | "Set Up AI in Zed" |
378| **Guide** | Deeper task-oriented content | "Vim Mode" |
379| **Concept** | Explanatory, mental models | "Key Concepts" |
380| **Reference** | Lookup-only, tables/lists | "All Settings" |