search

zed-industries / zed

Code at the speed of thought – Zed is a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter.
https://zed.dev
Other
47k stars 2.7k forks source link

Vim docs could be more structured and approachable for new users (proposal) #17215

Open NathanLovato opened 2 weeks ago

NathanLovato commented 2 weeks ago

Check for existing issues

Describe the feature

This issue is a little proposal for a contribution I'd like to make to the docs for vim mode.

Currently, the Vim mode docs page provides valuable information, but it could use a little more structure (it bounces back and forth between configuration and explaining differences in Zed's emulation layer), and it sometimes assumes some understanding of Zed and non-basic nvim ecosystem details.

I'd like to make it more approachable for new users and clearly separate the parts about configuring vs using the vim mode.

For that, besides editing, I would split the vim docs into two pages:

  1. Under the Configuring section, a page only about configuring the vim mode: toggling vim mode, settings, keymap, and using the context in custom keymap entries.
  2. Under Using Zed, a page about using the vim mode and all the provided key bindings and features. It would talk about toggling vim mode, vim mode design philosophy, provided features and commands, using the command palette, using Zed-specific additions, outline optional Vim mode features (surround, camelCase word navigation, etc.).

The two pages would cross-link.

In terms of edits, I'd like to format keybindings presented as code blocks in tables, similarly to other pages, and flesh out the text to improve precision and accessibility.

I started with a small set of edits in #17214 so you can tell me if you'd like any changes to the writing style. I'd gladly continue from there. Please let me know if you'd like this approached differently.

I'd also tackle #15591 as part of this work, in a single or multiple PRs, whichever works best for you.

If applicable, add mockups / screenshots to help present your vision of the feature

No response

ConradIrwin commented 1 week ago

Thanks for the idea here!

I think most people reading the page are likely familiar with vim (though as time goes on, Zed is more and more people's "first vim" which is exciting :D).

I think having an overview page makes sense; this is serving two purposes today: as a "sales pitch" on 'no really Zed's vim mode is (probably) not as awful as other vim clones you've tried' and as a jumping off point for people who are using it but want to customize it more.

In that vein it probably makes sense to split them as you describe; but I want to make sure that people who find themselves on the wrong page can easily get to the other.

NathanLovato commented 1 week ago

Thanks for the feedback! Note taken. I'll prep something on my next day off - probably Monday - and make sure to include cross-links.

And thanks for all your work, too! After Emacs, this is the only vim emulation that really feels like it meshes really well with the code editor and is solid as a daily driver already.